Update Agent

Update Ai Agent

curl --request PATCH \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Updated Agent Name",
  "instructions": {
    "general": "Updated instructions for the agent",
    "role": [
      "Customer service expert",
      "Problem solver"
    ],
    "goal": [
      "Resolve customer issues efficiently"
    ]
  },
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929"
}
'

{
  "id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
  "name": "Updated Agent Name",
  "description": "Answers product questions using web search and documentation",
  "icon": "🚀",
  "status": "ACTIVE",
  "deployment_type": "serverless",
  "created_at": "2026-02-05T18:54:51.388334Z",
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "framework": "agno",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "tools": [
    {
      "id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "method": "post",
      "path": "/operation/XpanderEmailServiceSendEmailWithHtmlOrTextContent/messaging/send_email"
    }
  ],
  "graph": [
    {
      "id": "124fe641-c1dc-4a2a-89d0-36f9bda2df75",
      "item_id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "type": "tool",
      "targets": [],
      "is_first": false
    }
  ],
  "knowledge_bases": [],
  "instructions": {
    "role": [
      "Customer service expert",
      "Problem solver"
    ],
    "goal": [
      "Resolve customer issues efficiently"
    ],
    "general": "Updated instructions for the agent"
  },
  "output_format": "text",
  "expected_output": "Short answer, formatted in rich markdown text.",
  "webhook_url": "https://webhook.xpander.ai/?agent_id=93a1cd50-2af0-452a-99a0-6e1f1b14fb29&asynchronous=false",
  "unique_name": "emerald-emu",
  "llm_api_base": null,
  "has_pending_changes": false,
  "llm_settings": [
    {
      "type": "before",
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "temperature": 0
    }
  ],
  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "coordinate_mode": true,
    "num_history_runs": 20,
    "tool_call_limit": 0
  }
}

PATCH

agents

{agent_id}

Update Ai Agent

curl --request PATCH \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Updated Agent Name",
  "instructions": {
    "general": "Updated instructions for the agent",
    "role": [
      "Customer service expert",
      "Problem solver"
    ],
    "goal": [
      "Resolve customer issues efficiently"
    ]
  },
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929"
}
'

{
  "id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
  "name": "Updated Agent Name",
  "description": "Answers product questions using web search and documentation",
  "icon": "🚀",
  "status": "ACTIVE",
  "deployment_type": "serverless",
  "created_at": "2026-02-05T18:54:51.388334Z",
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "framework": "agno",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "tools": [
    {
      "id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "method": "post",
      "path": "/operation/XpanderEmailServiceSendEmailWithHtmlOrTextContent/messaging/send_email"
    }
  ],
  "graph": [
    {
      "id": "124fe641-c1dc-4a2a-89d0-36f9bda2df75",
      "item_id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "type": "tool",
      "targets": [],
      "is_first": false
    }
  ],
  "knowledge_bases": [],
  "instructions": {
    "role": [
      "Customer service expert",
      "Problem solver"
    ],
    "goal": [
      "Resolve customer issues efficiently"
    ],
    "general": "Updated instructions for the agent"
  },
  "output_format": "text",
  "expected_output": "Short answer, formatted in rich markdown text.",
  "webhook_url": "https://webhook.xpander.ai/?agent_id=93a1cd50-2af0-452a-99a0-6e1f1b14fb29&asynchronous=false",
  "unique_name": "emerald-emu",
  "llm_api_base": null,
  "has_pending_changes": false,
  "llm_settings": [
    {
      "type": "before",
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "temperature": 0
    }
  ],
  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "coordinate_mode": true,
    "num_history_runs": 20,
    "tool_call_limit": 0
  }
}

Modify an agent’s configuration. Only provided fields will be updated. At least one field must be provided.

Path Parameters

agent_id

string

required

Unique identifier of the agent to update (UUID format)

Request Body

name

string

Display name for the agent

description

string

Description of the agent’s purpose and capabilities

instructions

object

System instructions configuration

Show Instructions Object

role

array

Array of role descriptions

goal

array

Array of goal descriptions

general

string

General instructions text

icon

string

Emoji icon representing the agent

model_provider

string

AI model provider (e.g., openai)

model_name

string

Specific model version (e.g., gpt-4o, gpt-4.1)

status

string

Agent status (enum: ACTIVE, INACTIVE)

llm_api_base

string

Custom API base URL for LLM provider (for AI Gateway configurations)

llm_extra_headers

object

Custom HTTP headers to include in LLM requests for gateway integration

should_reset_graph

boolean

Reset the agent’s graph configuration (default: false)

environment_id

string

Target environment ID

Response

Returns the updated AIAgent object with all current configuration.

Example Request

curl -X PATCH -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "model_provider": "anthropic",
    "model_name": "claude-sonnet-4-5-20250929",
    "instructions": {
      "role": [
        "Always greet the customer warmly",
        "Search the knowledge base before answering",
        "Escalate billing issues"
      ],
      "goal": [
        "Resolve customer inquiries on first contact",
        "Maintain a friendly tone"
      ],
      "general": "You are a customer support agent..."
    }
  }' \
  https://api.xpander.ai/v1/agents/<agent-id>

Example Response

{
  "id": "<agent-id>",
  "unique_name": "customer-support-agent",
  "name": "Customer Support Agent",
  "status": "ACTIVE",
  "organization_id": "<org-id>",
  "deployment_type": "serverless",
  "framework": "agno",
  "type": "manager",
  "version": 2,
  "has_pending_changes": false,
  "is_latest": false,
  "instructions": {
    "role": [
      "Always greet the customer warmly",
      "Search the knowledge base before answering",
      "Escalate billing issues"
    ],
    "goal": [
      "Resolve customer inquiries on first contact",
      "Maintain a friendly tone"
    ],
    "general": "You are a customer support agent..."
  },
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "tools": [],
  "knowledge_bases": []
}

Info

The PATCH endpoint updates agent configuration fields such as name, instructions, model_provider, model_name, output_format, and expected_output. To attach tools or knowledge bases, use the xpander.ai platform or the Python SDK.

Notes

At least one field must be provided in the request body
Only the specified fields will be updated
Other fields remain unchanged
Changes via PATCH take effect immediately for new invocations
Use Deploy Agent to publish a new version
Model provider and model name changes take effect immediately
The endpoints attached_tools, knowledge_bases, and graph are not supported via PATCH

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

agent_id

string

required

Body

application/json

name

string | null

Display name for the agent

instructions

AIAgentInstructions · object

System instructions configuration

Show child attributes

icon

string | null

Emoji icon representing the agent

should_reset_graph

boolean | null

Reset the agent's graph configuration (default: false)

model_provider

string | null

AI model provider (e.g., openai, anthropic)

environment_id

string | null

Target environment ID

model_name

string | null

Specific model version (e.g., gpt-4o, gpt-4.1, claude-sonnet-4-5-20250929)

status

enum<string> | null

Agent status (enum: ACTIVE, INACTIVE)

Available options:

DRAFT,

ACTIVE,

INACTIVE

Response

Successful Response

string | null

deployment_type

enum<string> | null

Available options:

serverless,

container

name

string

Display name of the agent

framework

string | null

Agent framework used (e.g., agno)

description

string | null

Description of the agent's purpose and capabilities

tools

any[] | null

Array of tools available to the agent

icon

string | null

Emoji icon representing the agent

instructions

AIAgentInstructions · object

Show child attributes

graph

AIAgentGraphItem · object[] | null

Show child attributes

status

enum<string> | null

Current deployment status: ACTIVE or INACTIVE

Available options:

DRAFT,

ACTIVE,

INACTIVE

knowledge_bases

AgentKnowledgeBase · object[] | null

Array of knowledge bases attached to the agent

Show child attributes

organization_id

string

UUID of the organization that owns this agent

created_at

string<date-time> | null

type

enum<string> | null

Enumeration of the agent types.

Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL.

Available options:

manager,

regular,

a2a,

curl

model_provider

enum<string> | null

AI model provider (e.g., openai, anthropic)

Available options:

openai,

nim,

amazon_bedrock,

huggingFace,

friendlyAI,

anthropic,

gemini,

fireworks,

google_ai_studio,

helicone,

open_router,

nebius

model_name

string | null

Specific model version (e.g., gpt-4o, gpt-4.1, claude-sonnet-4-5-20250929)

output_format

enum<string> | null

Output format: markdown or json

Available options:

text,

markdown,

json

output_schema

Output Schema · object

JSON schema for structured output when output_format is json

expected_output

string | null

Natural-language description of the desired output (e.g., "A bulleted list of key findings")

webhook_url

string

Auto-generated webhook URL for agent invocations

unique_name

string

Auto-generated unique identifier for the agent (e.g. 'emerald-emu')

llm_api_base

string | null

Custom LLM API base URL for self-hosted or proxied model endpoints

llm_settings

AIAgentGraphItemLLMSettings · object[]

LLM configuration per graph node (provider, model, temperature)

Show child attributes

agno_settings

AgnoSettings · object

Agno framework settings (memory, session storage, moderation, tool limits)

Show child attributes

has_pending_changes

boolean

Whether the agent has unpublished configuration changes

Get Agent Deploy Agent

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

Path Parameters

Request Body

Response

Example Request

Example Response

Info

Notes

Authorizations

Path Parameters

Body

Response

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Info

​Notes

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Response

Example Request

Example Response

Info

Notes