Skip to main content
PATCH
Update Ai Agent
Modify an agent’s configuration. Only provided fields will be updated. At least one field must be provided.
To add or remove tools (connector actions, custom functions, MCP servers, sub-agents, workflows), prefer the dedicated agent tools endpoints — List / Add / Remove. They handle catalog resolution and graph wiring for you, instead of hand-editing low-level graph/attached_tools.

Path Parameters

string
required
Unique identifier of the agent to update (UUID format)

Query Parameters

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

string
Display name for the agent
string
Description of the agent’s purpose and capabilities
object
System instructions configuration
string
Emoji icon representing the agent
string
AI model provider (e.g., openai)
string
Specific model version (e.g., gpt-4o, gpt-4.1)
string
Agent status (enum: ACTIVE, INACTIVE)
string
Custom API base URL for LLM provider (for AI Gateway configurations)
object
Custom HTTP headers to include in LLM requests for gateway integration
string
Reasoning effort level for the LLM (e.g., low, medium, high)
string
Output format: text or json
object
JSON schema for structured output when output_format is json
string
Natural-language description of the desired output
string
Target environment ID
string
Access control scope: personal or organizational
string
Agent type: manager, regular, a2a, curl
array
Array of connector tool attachments with connection IDs and selected operation IDs
array
Agent workflow graph configuration defining tool execution order
array
Array of knowledge base IDs to attach to the agent
object
Advanced agent settings including memory, session storage, tool limits, and safety features
object
Task-level strategies for retry, stop conditions, and iteration
object
Notification configuration (Slack, email, webhook) for agent events
object
Deep planning configuration for complex multi-step tasks
string
Voice ID for text-to-speech output
array
Source node configurations (e.g., Slack, web UI triggers)
boolean
Whether the agent requires human approval for tool calls

Response

Returns the updated AIAgent object with all current configuration.

Example Request

Example Response

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,
cerebras,
open_router,
nebius,
cloudflare_ai_gw,
z_ai
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 | null

Direct LLM credentials object.

llm_extra_headers
Llm Extra Headers · object | null

Additional HTTP headers for LLM requests.

instructions
AIAgentInstructions · object | null

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 | null

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.

tools
(AddActionTool · object | AddCustomFunctionTool · object | AddMcpTool · object | AddSubAgentTool · object | AddWorkflowTool · object | AddSkillTool · object)[] | null

Tools to attach in the unified simplified shape (same payload as POST /v1/agents/{agent_id}/tools). Additive: these are resolved and merged on top of the agent's existing tools (nothing is removed — use DELETE /v1/agents/{agent_id}/tools/{tool_id} to remove). See CreateAgentRequest.tools for the per-type shape.

Attach connector operations as agent tools.

attached_tools
Connector · object[] | null

Advanced/low-level: connector connections with operation IDs. Prefer tools. See CreateAgentRequest.attached_tools for full documentation.

graph
AIAgentGraphItem · object[] | null

Advanced/low-level: the agent's tool graph. Prefer tools. 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 | null

Agno framework settings.

task_level_strategies
TaskLevelStrategies · object | null

Task execution strategies.

notification_settings
NotificationSettings · object | null

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.

is_autonomous
boolean | null

Run the agent in autonomous mode.

discoverable
boolean | null

Expose the agent to agent-discovery surfaces (e.g. omni).

with_auto_context_management
boolean | null

Run the SDK automatic context optimizer.

developer_access
boolean | null

Allow invocation from the developer API and webhooks.

should_stage_before_publish
boolean | null

Stage edits as a draft before publishing.

can_self_schedule
boolean | null

Allow the agent to schedule its own future runs.

max_self_schedules
integer | null

Per-task lifetime cap on chained self-schedules.

Required range: 1 <= x <= 1000
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
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:true
enforce_deep_planning
boolean | null
default:true
use_agent_gateway
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 | null
oas
Oas · object | null
graph
AIAgentGraphItem · object[] | null
is_omni
boolean | null
default:false
skills
Skills · 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:amazon_bedrock
Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
cerebras,
open_router,
nebius,
cloudflare_ai_gw,
z_ai
model_name
string | null
default:global.anthropic.claude-sonnet-5
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 | null
llm_credentials_key
string | null
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
llm_credentials
LLMCredentials · object | null
llm_extra_headers
Llm Extra Headers · object | null
expected_output
string | null
default:""
agno_settings
AgnoSettings · object | null
on_prem_event_streaming
boolean | null
default:true
is_supervised
boolean | null
default:false
orchestration_nodes
OrchestrationNode · object[] | null
notification_settings
NotificationSettings · object | null

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. on_budget: Notifications to send on budget threshold crossings. A dedicated category — budget alerts are not errors.

task_level_strategies
TaskLevelStrategies · object | null

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).

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
can_self_schedule
boolean | null
default:false
max_self_schedules
integer | null
default:3
Required range: 1 <= x <= 1000
use_dynamic_tools
boolean | null
default:false
workspace_tools_enabled
boolean | null
default:true
is_autonomous
boolean | null
default:false
discoverable
boolean | null
default:true
with_auto_context_management
boolean | null
default:true
developer_access
boolean | null
default:true
should_stage_before_publish
boolean | null
default:true