Table of Contents

Creating Agents via Core API

This guide explains how to programmatically create agents using the Core API's /management endpoint path. This enables self-service agent creation similar to the User Portal agent creation wizard.

Overview

Agent creation via API allows you to:

  • Automate agent provisioning
  • Create agents from templates
  • Build custom agent management interfaces
  • Integrate agent creation into CI/CD pipelines

Important: Core API Only

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

URL Pattern:

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. Agents Contributor or Contributor role - Required to create agents
  3. AI Model - An AI model resource must exist (accessible via Core API's /management endpoint)
  4. Prompt (optional) - A prompt resource for the agent's system prompt

Authentication

Obtain an Entra ID bearer token:

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

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"
    }

Step 1: Check Agent Name Availability

Before creating an agent, verify the name is available:

Using curl

curl -X POST "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents/checkname" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "generic-agent",
    "name": "my-new-agent"
  }'

Response:

{
  "name": "my-new-agent",
  "type": "generic-agent",
  "status": "Allowed",
  "exists": false,
  "deleted": false,
  "message": null
}

Using Python

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():
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def check_agent_name_availability(name):
    """Check if an agent name is available."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/checkname"
    payload = {"type": "generic-agent", "name": name}
    
    response = requests.post(url, headers=get_headers(), json=payload, verify=False)
    response.raise_for_status()
    return response.json()

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

Step 2: List Available AI Models (Optional)

Find available AI models for your agent:

def list_ai_models():
    """List available AI models via Core API's management endpoint."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.AIModel/aiModels"
    
    response = requests.get(url, headers=get_headers())
    response.raise_for_status()
    return response.json()

# Find models
models = list_ai_models()
for model in models:
    resource = model.get('resource', {})
    print(f"Model: {resource.get('name')} ({resource.get('display_name')})")

Step 3: Create the Agent

Method 1: Direct Agent Creation

Create an agent by POSTing a complete agent payload:

Using curl

curl -X POST "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents/my-new-agent" `
  -H "Authorization: Bearer $TOKEN" `
  -H "Content-Type: application/json" `
  -d '{
    "type": "generic-agent",
    "name": "my-new-agent",
    "display_name": "My New Agent",
    "description": "An agent created via API",
    "conversation_history_settings": {
      "enabled": true,
      "max_history": 5
    },
    "shielding_settings": {
      "pre_completion_plugins": [],
      "post_completion_plugins": []
    },
    "orchestration_settings": {
      "agent_parameters": {}
    }
  }'

Using Python

def create_agent(agent_config):
    """Create a new agent via Core API's management endpoint."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent_config['name']}"
    
    response = requests.post(url, headers=get_headers(), json=agent_config, timeout=300)
    response.raise_for_status()
    return response.json()

# Create a basic agent
agent_config = {
    "type": "generic-agent",
    "name": "my-new-agent",
    "display_name": "My New Agent",
    "description": "An agent created via API",
    "conversation_history_settings": {
        "enabled": True,
        "max_history": 5
    },
    "shielding_settings": {
        "pre_completion_plugins": [],
        "post_completion_plugins": []
    },
    "orchestration_settings": {
        "agent_parameters": {}
    }
}

result = create_agent(agent_config)
print(f"Created agent: {result.get('object_id')}")

Response:

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

Method 2: Create from Agent Template

If agent templates are provided in your deployment, you can create agents from named agent templates:

# 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():
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def create_agent_from_template(
    template_name,
    agent_name,
    agent_display_name,
    main_llm,
    main_knowledge_llm,
    agent_expiration_date="",
    agent_description="",
    agent_welcome_message=""
):
    """Create an agent from the specified agent template."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agentTemplates/{template_name}/create-new"
    
    payload = {
        "template_parameters": {
            "AGENT_NAME": agent_name,
            "AGENT_DISPLAY_NAME": agent_display_name,
            "AGENT_EXPIRATION_DATE": agent_expiration_date,
            "AGENT_DESCRIPTION": agent_description,
            "AGENT_WELCOME_MESSAGE": agent_welcome_message,
            "MAIN_LLM": main_llm,
            "MAIN_KNOWLEDGE_LLM": main_knowledge_llm
        }
    }
    
    try:
        response = requests.post(url, headers=get_headers(), json=payload, timeout=300, verify=False)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 403:
            print("Agent templates may not be available via Core API in this deployment")
            return None
        raise

# Create from a named agent template (if available)
result = create_agent_from_template(
    template_name="BasicAgentTemplate",
    agent_name="my-template-agent",
    agent_display_name="my-template-agent",
    main_llm="GPT4oCompletionAIModel",
    main_knowledge_llm="GPT4oCompletionAIModel"
)
print(result)

Note: Agent templates may be disabled via Core API management capabilities depending on your deployment configuration. If templates are unavailable, use the direct creation method.