Table of Contents

Agent Management via Core API

This reference documents how to manage agents using the Core API's /management endpoint path. This enables self-service agent creation, editing, and deletion for developers and end users.

Overview

The Core API exposes a restricted subset of management capabilities through the /management endpoint path. This is distinct from the full Management API, which is intended for administrative operations.

URL Patterns

Endpoint Type URL Pattern
Standard Core API https://{core-api-url}/instances/{instanceId}/...
Core API Management Endpoint https://{core-api-url}/management/instances/{instanceId}/providers/...

When to Use

Use the Core API management endpoint when:

  • Building self-service agent creation features
  • Programmatically managing agents from applications
  • Integrating agent management into developer workflows

Available Operations

Operations available through the Core API management endpoint are controlled by CoreManagementCapabilitiesService. The following agent operations are available:

HTTP Method Operations
GET agents, agents/{name}, agents/{name}/agentFiles
POST agents, agents/checkname, agents/{name}/set-owner
DELETE agents, agents/{name}/agentFiles

Authentication

The Core API management endpoint requires Entra ID bearer tokens only. Agent Access Tokens are NOT supported for management operations.

Header:

Authorization: Bearer <entra-id-jwt-token>

Getting a token with Azure CLI:

az login
TOKEN=$(az account get-access-token \
  --resource api://{core-api-client-id} \
  --query accessToken -o tsv)

Authorization (RBAC)

Access to agent management operations is controlled by role-based access control:

Operation Required Role
GET agents Reader
GET agents/{name} Reader
POST agents (create) Agents Contributor or Contributor
POST agents (update) Agents Contributor or Contributor
DELETE agents Owner (on the agent)
POST agents/checkname Agents Contributor or Contributor
POST agents/{name}/set-owner Owner (on the agent)

Authentication + RBAC Quick Reference

Standard Core API Endpoints

Endpoint Auth Methods Access Rules
POST /completions Entra ID or Agent Access Token Requires access to target agent
POST /async-completions Entra ID or Agent Access Token Requires access to target agent
POST /sessions, GET /sessions Entra ID or Agent Access Token Session scoping rules apply
GET /sessions/{id}/messages Entra ID or Agent Access Token Session scoping rules apply
DELETE /sessions/{id} Entra ID or Agent Access Token Session scoping rules apply
POST /files/upload Entra ID or Agent Access Token File scoping rules apply
GET /files/{provider}/{fileId} Entra ID or Agent Access Token File scoping rules apply
POST /files/delete Entra ID or Agent Access Token File scoping rules apply
GET /completions/agents Entra ID or Agent Access Token Response includes roles and actions

Core API Management Endpoint

Endpoint Auth Methods Access Rules
.../providers/FoundationaLLM.Agent/agents* Entra ID only RBAC controls create/edit/delete
.../providers/FoundationaLLM.Prompt/prompts* Entra ID only Used to support agent configuration
.../providers/FoundationaLLM.AIModel/aiModels* Entra ID only Used to support agent configuration

Query Parameters:

  • includeRoles: Include RBAC roles in GET responses
  • includeActions: Include authorized actions in GET responses

Endpoints Reference

List Agents

Retrieve all agents accessible to the current user.

GET {core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents

curl Example:

curl -X GET "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Python Example:

import os
import requests

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

def get_headers():
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def list_agents():
    """List all agents via Core API's management endpoint."""
    url = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/providers/FoundationaLLM.Agent/agents"
    response = requests.get(url, headers=get_headers())
    response.raise_for_status()
    return response.json()

Response (200 OK):

[
  {
    "resource": {
      "name": "my-agent",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent",
      "display_name": "My Agent",
      "description": "Agent description"
    },
    "roles": ["Owner"],
    "actions": ["read", "write", "delete"]
  }
]

Get Agent

Retrieve a single agent by name.

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

curl Example:

curl -X GET "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Python Example:

def get_agent(agent_name: str):
    """Get a single agent via Core API's management endpoint."""
    url = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/providers/FoundationaLLM.Agent/agents/{agent_name}"
    response = requests.get(url, headers=get_headers())
    response.raise_for_status()
    return response.json()

Response (200 OK):

[
  {
    "resource": {
      "type": "agent",
      "name": "my-agent",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent",
      "display_name": "My Agent",
      "description": "Agent description",
      "conversation_history_settings": {
        "enabled": true,
        "max_history": 5
      },
      "shielding_settings": {
        "pre_completion_plugins": [],
        "post_completion_plugins": []
      },
      "workflow_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/my-workflow"
    },
    "roles": ["Owner"],
    "actions": ["read", "write", "delete"]
  }
]

Create or Update Agent

Create a new agent or update an existing one using POST.

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

curl Example:

curl -X POST "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-new-agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent",
    "name": "my-new-agent",
    "display_name": "My New Agent",
    "description": "A new agent created via API",
    "conversation_history_settings": {
      "enabled": true,
      "max_history": 5
    },
    "shielding_settings": {
      "pre_completion_plugins": [],
      "post_completion_plugins": []
    }
  }'

Python Example:

def upsert_agent(agent_object: dict):
    """Create or update an agent via Core API's management endpoint."""
    url = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/providers/FoundationaLLM.Agent/agents/{agent_object['name']}"
    
    response = requests.post(url, headers=get_headers(), json=agent_object, timeout=300)
    response.raise_for_status()
    return response.json()

# Example usage
agent = {
    "type": "agent",
    "name": "my-new-agent",
    "display_name": "My New Agent",
    "description": "A new agent created via API",
    "conversation_history_settings": {
        "enabled": True,
        "max_history": 5
    },
    "shielding_settings": {
        "pre_completion_plugins": [],
        "post_completion_plugins": []
    }
}
result = upsert_agent(agent)

Response (200 OK):

{
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-new-agent",
  "resource_exists": false
}

Delete Agent

Delete an agent. This performs a soft delete.

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

curl Example:

curl -X DELETE "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent" \
  -H "Authorization: Bearer $TOKEN"

Python Example:

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

Response (200 OK): Empty body on success.

Note: Purge (permanent delete) is only available through the full Management API, not via the Core API management endpoint.

Check Agent Name Availability

Validate that an agent name is available before creating.

POST {core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/checkname

curl Example:

curl -X POST "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/checkname" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "generic-agent",
    "name": "my-proposed-agent-name"
  }'

Python Example:

def check_agent_name_availability(name: str) -> dict:
    """Check if an agent name is available via Core API's management endpoint."""
    url = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/providers/FoundationaLLM.Agent/agents/checkname"
    payload = {"type": "generic-agent", "name": name}
    
    response = requests.post(url, headers=get_headers(), json=payload)
    response.raise_for_status()
    return response.json()

# Check before creating
result = check_agent_name_availability("my-proposed-agent-name")
if result.get("status") == "Allowed":
    print("Name is available")
else:
    print(f"Name unavailable: {result.get('message')}")

Response (200 OK):

{
  "name": "my-proposed-agent-name",
  "type": "generic-agent",
  "status": "Allowed",
  "message": null
}

Set Agent Owner

Transfer ownership of an agent to another user.

POST {core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/set-owner

curl Example:

curl -X POST "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent/set-owner" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_user_id": "00000000-0000-0000-0000-000000000001"
  }'

Python Example:

def set_agent_owner(agent_name: str, owner_user_id: str):
    """Set the owner of an agent via Core API's management endpoint."""
    url = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/providers/FoundationaLLM.Agent/agents/{agent_name}/set-owner"
    payload = {"owner_user_id": owner_user_id}
    
    response = requests.post(url, headers=get_headers(), json=payload)
    response.raise_for_status()
    return response.json()

Agent JSON Structure

When creating or updating agents, use the following JSON structure:

{
  "type": "agent",
  "name": "my-agent",
  "display_name": "My Agent",
  "description": "Agent description",
  "conversation_history_settings": {
    "enabled": true,
    "max_history": 5
  },
  "shielding_settings": {
    "pre_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-AzureContentSafety" }
    ],
    "post_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-Presidio" }
    ]
  },
  "orchestration_settings": {
    "agent_parameters": {}
  },
  "workflow_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/my-workflow",
  "tool_object_ids": [],
  "cost_center": "",
  "expiration_date": null
}

Field Descriptions

Field Type Description
type string Resource type (always agent)
name string Unique agent identifier (alphanumeric, dashes, underscores)
display_name string User-friendly display name
description string Agent description
conversation_history_settings.enabled boolean Enable conversation history
conversation_history_settings.max_history integer Number of message pairs to retain
shielding_settings.pre_completion_plugins array Plugins that screen the user prompt. Empty disables prompt shielding.
shielding_settings.post_completion_plugins array Plugins that screen the model response. Empty disables response shielding.
workflow_object_id string Reference to the agent's workflow
tool_object_ids array References to agent tools
cost_center string Optional cost allocation identifier
expiration_date string Optional ISO-8601 expiration date

See Agents and Workflows for complete schema documentation.

Supporting Operations

Read AI Models

List available AI models for agent configuration.

GET {core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels

curl Example:

curl -X GET "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels" \
  -H "Authorization: Bearer $TOKEN"

Read Prompts

List available prompts for agent configuration.

GET {core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts

curl Example:

curl -X GET "https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts" \
  -H "Authorization: Bearer $TOKEN"

Error Handling

Status Description Common Causes
400 Bad Request Invalid JSON, missing required fields
401 Unauthorized Missing or invalid bearer token
403 Forbidden Insufficient RBAC permissions, or operation not available via Core API
404 Not Found Agent or resource not found
409 Conflict Agent name already exists
500 Internal Server Error Resource provider error

Error Response Example:

{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request body is invalid.",
  "instance": "/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent"
}