Skip to main content
PATCH
/
v1
/
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 '
{
  "organization_id": "<string>",
  "agent_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "icon": "<string>",
  "avatar": "<string>",
  "model_name": "<string>",
  "llm_api_base": "<string>",
  "llm_credentials_key": "<string>",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "expected_output": "<string>",
  "output_schema": {},
  "framework": "<string>",
  "deep_planning": true,
  "enforce_deep_planning": true,
  "attached_tools": [
    {
      "id": "<string>",
      "operation_ids": [
        "<string>"
      ]
    }
  ],
  "graph": [
    {
      "item_id": "<string>",
      "targets": [
        "<string>"
      ],
      "id": "<string>",
      "name": "<string>",
      "settings": {
        "instructions": "<string>",
        "description": "<string>",
        "schemas": {
          "input": {},
          "output": {}
        },
        "advanced_filtering_options": {
          "returnables": [
            "<string>"
          ],
          "searchables": [
            "<string>"
          ],
          "globally_enabled": false
        },
        "hitl_options": {
          "title": "<string>",
          "description": "<string>",
          "recipients": [
            "<string>"
          ],
          "slack_app": "<string>",
          "should_approve_with_current_user": true
        },
        "a2a_options": {
          "url": "<string>"
        },
        "coding_agent_settings": {
          "type": "codex"
        },
        "mcp_settings": {
          "type": "remote",
          "name": "<string>",
          "command": "<string>",
          "url": "<string>",
          "transport": "streamable-http",
          "auth_type": "none",
          "api_key": "<string>",
          "use_secrets_manager": false,
          "client_id": "<string>",
          "client_secret": "<string>",
          "additional_scopes": [],
          "headers": {},
          "env_vars": {},
          "allowed_tools": [],
          "share_user_token_across_other_agents": true
        },
        "use_cache": false
      },
      "is_first": false
    }
  ],
  "knowledge_bases": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "rw": false,
      "documents": []
    }
  ],
  "source_nodes": [
    {
      "id": "<string>",
      "targets": [
        "<string>"
      ],
      "metadata": {}
    }
  ],
  "environment_id": "<string>",
  "connectivity_details": {
    "agent_url": "<string>",
    "custom_headers": {},
    "auth_type": "none",
    "api_key_header_name": "X-API-Key",
    "auth_value": "<string>"
  },
  "agno_settings": {
    "session_storage": true,
    "learning": false,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "openai_moderation_categories": [
      "<string>"
    ],
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "threshold": 3,
      "instructions": ""
    },
    "max_plan_retries": 15,
    "plan_retry_strategy": "tiered"
  },
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "notification_settings": {
    "on_success": {},
    "on_error": {}
  },
  "voice_id": "<string>",
  "using_nemo": true,
  "is_supervised": true,
  "on_prem_event_streaming": true,
  "orchestration_nodes": [
    {
      "definition": {
        "code": "<string>"
      },
      "id": "<string>",
      "next_node_ids": [
        "<string>"
      ],
      "name": "<string>",
      "description": "<string>",
      "condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      },
      "retry_strategy": {
        "enabled": false,
        "max_retries": 3
      },
      "iterative_strategy": {
        "enabled": false,
        "max_iterations": 3,
        "end_condition": {
          "term": "<string>",
          "group_id": "<string>",
          "path": "<string>",
          "value": null
        }
      },
      "stop_strategy": {
        "enabled": false,
        "stop_on_failure": true,
        "stop_on_condition": {
          "term": "<string>",
          "group_id": "<string>",
          "path": "<string>",
          "value": null
        }
      },
      "input_type": "text",
      "input_schema": {},
      "input_instructions": "<string>",
      "agentic_context_input_instructions": "<string>",
      "agentic_context_output_instructions": "<string>",
      "return_this": false
    }
  ],
  "use_oidc_pre_auth": true,
  "pre_auth_audiences": [
    "<string>"
  ],
  "use_oidc_pre_auth_token_for_llm": true,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}
'
{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "created_by_details": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>"
  },
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "environment_id": "<string>",
  "deployment_type": "serverless",
  "prompts": [],
  "is_latest": false,
  "has_pending_changes": false,
  "deep_planning": false,
  "enforce_deep_planning": false,
  "connectivity_details": {},
  "framework": "agno",
  "description": "",
  "tools": [],
  "icon": "🚀",
  "avatar": "male-avatar",
  "source_nodes": [],
  "attached_tools": [],
  "access_scope": "personal",
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "oas": {},
  "graph": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "using_nemo": false,
  "deletable": true,
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-6",
  "llm_reasoning_effort": "medium",
  "llm_api_base": "<string>",
  "output_format": "markdown",
  "voice_id": "<string>",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "expected_output": "",
  "agno_settings": {
    "session_storage": true,
    "learning": false,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "instructions": "",
      "threshold": 3
    },
    "max_plan_retries": 15,
    "plan_retry_strategy": "tiered"
  },
  "on_prem_event_streaming": true,
  "is_supervised": false,
  "orchestration_nodes": [],
  "notification_settings": {},
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "use_oidc_pre_auth": false,
  "pre_auth_audiences": [],
  "use_oidc_pre_auth_token_for_llm": false,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

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)

​
Query Parameters

​
deploy
boolean
default:false
Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a separate PUT deploy call.

​
Request Body

​
name
string
Display name for the agent
​
description
string
Description of the agent’s purpose and capabilities
​
instructions
object
System instructions configuration
​
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
​
llm_reasoning_effort
string
Reasoning effort level for the LLM (e.g., low, medium, high)
​
output_format
string
Output format: text or json
​
output_schema
object
JSON schema for structured output when output_format is json
​
expected_output
string
Natural-language description of the desired output
​
environment_id
string
Target environment ID
​
access_scope
string
Access control scope: personal or organizational
​
type
string
Agent type: manager, regular, a2a, curl
​
attached_tools
array
Array of connector tool attachments with connection IDs and selected operation IDs
​
graph
array
Agent workflow graph configuration defining tool execution order
​
knowledge_bases
array
Array of knowledge base IDs to attach to the agent
​
agno_settings
object
Advanced agent settings including memory, session storage, tool limits, and safety features
​
task_level_strategies
object
Task-level strategies for retry, stop conditions, and iteration
​
notification_settings
object
Notification configuration (Slack, email, webhook) for agent events
​
deep_planning
object
Deep planning configuration for complex multi-step tasks
​
voice_id
string
Voice ID for text-to-speech output
​
source_nodes
array
Source node configurations (e.g., Slack, web UI triggers)
​
is_supervised
boolean
Whether the agent requires human approval for tool calls

​
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..."
    },
    "access_scope": "personal"
  }' \
  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..."
  },
  "access_scope": "personal",
  "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, expected_output, and access_scope. 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
  • Use deploy=true query parameter to automatically deploy after updating
  • Without deploy=true, changes are staged and require a separate Deploy Agent call
  • attached_tools, knowledge_bases, and graph can now be updated via PATCH

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Query Parameters

​
deploy
boolean
default:false

Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.

Body

application/json

Request model for updating an existing AI agent.

All fields are optional — only provide the fields you want to change. At least one field must be provided. Fields not included in the request will retain their current values.

System-managed fields like organization_id, agent_id, id, status, version, etc. are set by the service layer and should not be provided.

​
organization_id
string | null

Set automatically by the API service from the authenticated request.

​
agent_id
string | null

Set automatically by the API service from the URL path parameter.

​
name
string | null

Human-readable name for the agent.

​
description
string | null

A brief description of what the agent does.

​
icon
string | null

Emoji icon displayed next to the agent name.

​
avatar
string | null

Avatar identifier for the agent's visual representation.

​
type
enum<string> | null

The agent type. Cannot be changed to 'orchestration' — use the Workflows API.

Available options:
manager,
regular,
a2a,
curl,
orchestration
​
status
enum<string> | null

Agent status. Set to 'ACTIVE' to enable or 'INACTIVE' to disable the agent.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
model_provider
enum<string> | null

The LLM provider to use.

Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null

The specific model identifier.

​
llm_reasoning_effort
enum<string> | null

Reasoning depth control.

Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null

Custom API base URL for the LLM provider.

​
llm_credentials_key
string | null

Reference key to stored LLM API credentials.

​
llm_credentials_key_type
enum<string> | null

Type of credential storage.

Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object

Direct LLM credentials object.

​
llm_extra_headers
Llm Extra Headers · object

Additional HTTP headers for LLM requests.

​
instructions
AIAgentInstructions · object

Structured instructions for the agent.

​
expected_output
string | null

Description of expected output format.

​
output_format
enum<string> | null

Response format.

Available options:
text,
markdown,
json,
voice
​
output_schema
Output Schema · object

JSON Schema for structured output.

​
framework
string | null

Execution framework.

​
deep_planning
boolean | null

Enable deep planning mode.

​
enforce_deep_planning
boolean | null

Force deep planning for all tasks.

​
attached_tools
Connector · object[] | null

Connector connections with operation IDs. See CreateAgentRequest.attached_tools for full documentation.

​
graph
AIAgentGraphItem · object[] | null

The agent's tool graph. See CreateAgentRequest.graph for full documentation.

​
knowledge_bases
AgentKnowledgeBase · object[] | null

Attached knowledge bases.

​
source_nodes
AIAgentSourceNode · object[] | null

Agent trigger entry points.

​
deployment_type
enum<string> | null

Deployment infrastructure.

Available options:
serverless,
container
​
access_scope
enum<string> | null

Access visibility scope.

Available options:
personal,
organizational
​
environment_id
string | null

Target deployment environment.

​
connectivity_details
AIAgentConnectivityDetailsA2A · object

External agent connection details.

​
agno_settings
AgnoSettings · object

Agno framework settings.

​
task_level_strategies
TaskLevelStrategies · object

Task execution strategies.

​
notification_settings
NotificationSettings · object

Task notification settings.

​
voice_id
string | null

Voice ID for TTS output.

​
using_nemo
boolean | null

Enable NeMo guardrails.

​
is_supervised
boolean | null

Enable supervised mode.

​
on_prem_event_streaming
boolean | null

Enable event streaming.

​
orchestration_nodes
OrchestrationNode · object[] | null

Workflow orchestration DAG nodes. Only for type=orchestration workflows.

​
use_oidc_pre_auth
boolean | null

Enable OIDC pre-authentication.

​
pre_auth_audiences
string[] | null

Allowed OIDC audiences.

​
use_oidc_pre_auth_token_for_llm
boolean | null

Forward OIDC token to LLM.

​
oidc_pre_auth_token_llm_audience
string | null

OIDC audience for LLM access.

​
oidc_pre_auth_token_mcp_audience
string | null

OIDC audience for MCP access.

Response

Successful Response

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
read-only
​
created_by_details
CreatedByDetails · object
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
environment_id
string | null
​
deployment_type
enum<string> | null
default:serverless
Available options:
serverless,
container
​
prompts
string[] | null
​
is_latest
boolean | null
default:false
​
has_pending_changes
boolean | null
default:false
​
deep_planning
boolean | null
default:false
​
enforce_deep_planning
boolean | null
default:false
​
connectivity_details
AIAgentConnectivityDetailsA2A · object
​
framework
string | null
default:agno
​
description
string | null
default:""
​
tools
any[] | null
​
icon
string | null
default:🚀
​
avatar
string | null
default:male-avatar
​
source_nodes
AIAgentSourceNode · object[] | null
​
attached_tools
Connector · object[] | null
​
access_scope
enum<string> | null
default:personal
Available options:
personal,
organizational
​
instructions
AIAgentInstructions · object
​
oas
Oas · object
​
graph
AIAgentGraphItem · object[] | null
​
status
enum<string> | null
default:ACTIVE

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
knowledge_bases
AgentKnowledgeBase · object[] | null
​
version
integer | null
default:1
​
created_by
string | null
​
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. Orchestration: marks the agent as an Orchestration object.

Available options:
manager,
regular,
a2a,
curl,
orchestration
​
using_nemo
boolean | null
default:false
​
deletable
boolean | null
default:true
​
model_provider
enum<string> | null
default:anthropic
Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null
default:claude-sonnet-4-6
​
llm_reasoning_effort
enum<string> | null
default:medium
Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object
​
llm_extra_headers
Llm Extra Headers · object
​
expected_output
string | null
default:""
​
agno_settings
AgnoSettings · object
​
on_prem_event_streaming
boolean | null
default:true
​
is_supervised
boolean | null
default:false
​
orchestration_nodes
OrchestrationNode · object[] | null
​
notification_settings
NotificationSettings · object

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations.

​
task_level_strategies
TaskLevelStrategies · object

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.
​
use_oidc_pre_auth
boolean | null
default:false
​
pre_auth_audiences
string[] | null
​
use_oidc_pre_auth_token_for_llm
boolean | null
default:false
​
oidc_pre_auth_token_llm_audience
string | null
​
oidc_pre_auth_token_mcp_audience
string | null