Update Agent
Update an existing AI agent’s configuration, tools, or knowledge bases
Path Parameters
Query Parameters
Request Body
openai)gpt-4o, gpt-4.1)ACTIVE, INACTIVE)low, medium, high)text or jsonoutput_format is jsonpersonal or organizationalmanager, regular, a2a, curlResponse
Returns the updatedAIAgent object with all current configuration.
Example Request
Example Response
Info
The PATCH endpoint updates agent configuration fields such asname, 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=truequery parameter to automatically deploy after updating - Without
deploy=true, changes are staged and require a separate Deploy Agent call attached_tools,knowledge_bases, andgraphcan now be updated via PATCH
Authorizations
API Key for authentication
Path Parameters
Query Parameters
Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.
Body
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.
Set automatically by the API service from the authenticated request.
Set automatically by the API service from the URL path parameter.
Human-readable name for the agent.
A brief description of what the agent does.
Emoji icon displayed next to the agent name.
Avatar identifier for the agent's visual representation.
The agent type. Cannot be changed to 'orchestration' — use the Workflows API.
manager, regular, a2a, curl, orchestration Agent status. Set to 'ACTIVE' to enable or 'INACTIVE' to disable the agent.
DRAFT, ACTIVE, INACTIVE The LLM provider to use.
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 The specific model identifier.
Reasoning depth control.
low, medium, high, xhigh Custom API base URL for the LLM provider.
Reference key to stored LLM API credentials.
Type of credential storage.
xpander, custom Direct LLM credentials object.
Additional HTTP headers for LLM requests.
Structured instructions for the agent.
Description of expected output format.
Response format.
text, markdown, json, voice JSON Schema for structured output.
Execution framework.
Enable deep planning mode.
Force deep planning for all tasks.
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.
- AddActionTool
- AddCustomFunctionTool
- AddMcpTool
- AddSubAgentTool
- AddWorkflowTool
- AddSkillTool
Advanced/low-level: connector connections with operation IDs. Prefer tools. See CreateAgentRequest.attached_tools for full documentation.
Advanced/low-level: the agent's tool graph. Prefer tools. See CreateAgentRequest.graph for full documentation.
Attached knowledge bases.
Agent trigger entry points.
Deployment infrastructure.
serverless, container Access visibility scope.
personal, organizational Target deployment environment.
External agent connection details.
- AIAgentConnectivityDetailsA2A
- AIAgentConnectivityDetailsCurl
- Connectivity Details
Agno framework settings.
Task execution strategies.
Task notification settings.
Voice ID for TTS output.
Enable NeMo guardrails.
Enable supervised mode.
Run the agent in autonomous mode.
Expose the agent to agent-discovery surfaces (e.g. omni).
Run the SDK automatic context optimizer.
Allow invocation from the developer API and webhooks.
Stage edits as a draft before publishing.
Allow the agent to schedule its own future runs.
Per-task lifetime cap on chained self-schedules.
1 <= x <= 1000Enable event streaming.
Workflow orchestration DAG nodes. Only for type=orchestration workflows.
Enable OIDC pre-authentication.
Allowed OIDC audiences.
Forward OIDC token to LLM.
OIDC audience for LLM access.
OIDC audience for MCP access.
Response
Successful Response
serverless, container - AIAgentConnectivityDetailsA2A
- AIAgentConnectivityDetailsCurl
- Connectivity Details
personal, organizational 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.
DRAFT, ACTIVE, INACTIVE 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.
manager, regular, a2a, curl, orchestration 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 low, medium, high, xhigh text, markdown, json, voice xpander, custom 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.
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).
1 <= x <= 1000
