Table of Contents

Deleting Agents via Core API

This guide explains how to delete agents using the Core API's /management endpoint path.

Overview

Agent deletion via the Core API performs a soft delete. The agent is marked as deleted but can be recovered by an administrator. Permanent deletion (purge) is only available through the full Management API.

Important: Core API Only

All agent management operations use the Core API's /management endpoint path. This is distinct from the full Management API.

URL Pattern:

DELETE https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}

Prerequisites

  1. Entra ID Authentication - Agent Access Tokens are NOT supported for management operations
  2. Owner role on the agent - Only agent owners can delete agents

Python Setup

import os
import requests

# Configuration
CORE_API_URL = os.getenv("FLLM_CORE_API_URL")
INSTANCE_ID = os.getenv("FLLM_INSTANCE_ID")
TOKEN = os.getenv("FLLM_TOKEN")

# Core API management endpoint base
CORE_API_MGMT = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/"

def get_headers():
    """Build headers for Core API requests."""
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

Deleting an Agent

Using curl

# Set environment variables
export CORE_API_URL="https://{your-core-api-url}"
export INSTANCE_ID="{your-instance-id}"
export TOKEN=$(az account get-access-token \
  --resource api://{core-api-client-id} \
  --query accessToken -o tsv)

# Delete the agent
curl -X DELETE "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents/my-agent" \
  -H "Authorization: Bearer $TOKEN"

Response: 200 OK with empty body on success.

Using Python

def delete_agent(agent_name):
    """Delete an agent via Core API's management endpoint."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent_name}"
    
    response = requests.delete(url, headers=get_headers())
    response.raise_for_status()
    return True

# Delete an agent
success = delete_agent("my-new-agent")
if success:
    print("Agent deleted successfully")

Important Notes

Soft Delete vs. Purge

  • Via Core API: Only soft delete is available. The agent is marked as deleted but can be recovered.
  • Via Management API: Both soft delete and purge (permanent delete) are available.

If you need to permanently delete an agent, use the full Management API.

Permission Requirements

  • You must have the Owner role on the agent to delete it
  • Agents Contributor or Contributor roles cannot delete agents

Recovery

Soft-deleted agents can be recovered by an administrator through the Management API. Contact your system administrator if you need to recover a deleted agent.