Table of Contents

Editing Agents via Core API

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

Overview

Editing agents via API allows you to:

  • Update agent display name and description
  • Modify conversation history settings
  • Change shielding plugin lists
  • Update orchestration parameters
  • Modify agent prompts

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:

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 update agents you have access to

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

Workflow: Get, Modify, Update

The typical workflow for editing an agent is:

  1. GET the current agent configuration
  2. Modify the desired fields and POST the updated configuration back

Step 1: Retrieve Current Agent Configuration

Using curl

curl -X GET "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents/my-new-agent" `
  -H "Authorization: Bearer $TOKEN"

Response Structure:

[
  {
    "resource": {
      "type": "agent",
      "name": "my-agent",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-new-agent",
      "display_name": "My Agent",
      "description": "Original description",
      "conversation_history_settings": {
        "enabled": true,
        "max_history": 5
      },
      "shielding_settings": {
        "pre_completion_plugins": [],
        "post_completion_plugins": []
      }
    },
    ...
  }
]

Using Python

def get_agent(agent_name):
    """Get the current agent configuration."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent_name}"
    
    response = requests.get(url, headers=get_headers())
    response.raise_for_status()
    
    result = response.json()
    
    # Response is an array with a single item containing the resource
    if isinstance(result, list) and len(result) > 0:
        return result[0].get('resource', result[0])
    return result

# Get current configuration
agent = get_agent("my-new-agent")
print(f"Current display name: {agent.get('display_name')}")

Step 2: Update the Agent

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 Updated Agent Name",
    "description": "Updated description via API",
    "conversation_history_settings": {
      "enabled": true,
      "max_history": 10
    },
    "shielding_settings": {
      "pre_completion_plugins": [],
      "post_completion_plugins": []
    }
  }'

Using Python

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

def get_agent(agent_name):
    """Get the current agent configuration."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent_name}"
    
    response = requests.get(url, headers=get_headers(), verify=False)
    response.raise_for_status()
    
    result = response.json()
    
    # Response is an array with a single item containing the resource
    if isinstance(result, list) and len(result) > 0:
        return result[0].get('resource', result[0])
    return result

def update_agent(agent):
    """Update an agent's configuration via Core API's management endpoint."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent['name']}"
    
    # Clean up the agent object before sending
    agent_copy = clean_agent_for_update(agent)
    
    response = requests.post(url, headers=get_headers(), json=agent_copy, timeout=300, verify=False)
    response.raise_for_status()
    return response.json()

def clean_agent_for_update(agent):
    """Clean up agent object for update (matching api.ts cleanup logic)."""
    # Create a copy without read-only fields
    cleaned = {k: v for k, v in agent.items() if k not in ['isReadonly', 'roles', 'actions']}
    
    # Convert empty strings to None for optional fields
    if cleaned.get('expiration_date') == '':
        cleaned['expiration_date'] = None
    if cleaned.get('cost_center') == '':
        cleaned['cost_center'] = None
    
    # Remove object_id if it's just going to be regenerated
    # (keep it if you need to preserve the reference)
    
    return cleaned


agent = get_agent("my-new-agent")
print(f"Current display name: {agent.get('display_name')}")

# Update agent
agent['display_name'] = "Updated Agent Name"
agent['description'] = "Updated via API"
result = update_agent(agent)
print(f"Agent updated: {result.get('object_id')}")