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>",
  "instructions": {
    "role": [
      "<string>"
    ],
    "goal": [
      "<string>"
    ],
    "general": "<string>"
  },
  "icon": "<string>",
  "should_reset_graph": true,
  "model_provider": "<string>",
  "environment_id": "<string>",
  "model_name": "<string>"
}'
{
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "delegation_end_strategy": "return-to-start",
  "environment_id": "<string>",
  "sub_agents_continuous_thread": true,
  "deployment_type": "serverless",
  "created_by_prompt": "<string>",
  "prompts": [
    "<string>"
  ],
  "name": "<string>",
  "framework": "<string>",
  "description": "<string>",
  "tools": [
    "<any>"
  ],
  "icon": "<string>",
  "avatar": "<string>",
  "source_nodes": [
    {
      "id": "<string>",
      "type": "workbench",
      "targets": [
        "<string>"
      ],
      "metadata": {}
    }
  ],
  "attached_tools": [
    {
      "id": "<string>",
      "operation_ids": [
        "<string>"
      ]
    }
  ],
  "access_scope": "personal",
  "instructions": {
    "role": [
      "<string>"
    ],
    "goal": [
      "<string>"
    ],
    "general": "<string>"
  },
  "oas": {},
  "graph": [
    {
      "id": "<string>",
      "item_id": "<string>",
      "name": "<string>",
      "type": "source_node",
      "sub_type": "sdk",
      "targets": [
        "<string>"
      ],
      "settings": {
        "instructions": "<string>",
        "description": "<string>",
        "schemas": {
          "input": {},
          "output": {}
        },
        "advanced_filtering_options": {
          "returnables": [
            "<string>"
          ],
          "searchables": [
            "<string>"
          ],
          "globally_enabled": true
        },
        "hitl_options": {
          "title": "<string>",
          "description": "<string>",
          "recipients": [
            "<string>"
          ],
          "hitl_type": "slack",
          "slack_app": "<string>",
          "should_approve_with_current_user": true
        },
        "a2a_options": {
          "url": "<string>"
        },
        "coding_agent_settings": {
          "type": "<string>"
        },
        "mcp_settings": {
          "type": "local",
          "name": "<string>",
          "command": "<string>",
          "url": "<string>",
          "transport": "stdio",
          "auth_type": "api_key",
          "api_key": "<string>",
          "headers": {},
          "env_vars": {},
          "allowed_tools": [
            "<string>"
          ]
        },
        "use_cache": true
      },
      "llm_settings": [
        {
          "type": "before",
          "provider": "<string>",
          "model": "<string>",
          "temperature": 123
        }
      ],
      "is_first": true
    }
  ],
  "llm_settings": [
    {
      "type": "before",
      "provider": "<string>",
      "model": "<string>",
      "temperature": 123
    }
  ],
  "status": "DRAFT",
  "knowledge_bases": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "strategy": "vanilla",
      "rw": true,
      "documents": [
        "<string>"
      ]
    }
  ],
  "version": 123,
  "organization_id": "<string>",
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "type": "manager",
  "delegation_type": "router",
  "delegation_memory_strategy": "full",
  "is_ai_employee": true,
  "using_nemo": true,
  "deletable": true,
  "model_provider": "openai",
  "model_name": "<string>",
  "llm_api_base": "<string>",
  "output_format": "text",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "description": "<string>",
    "value": "<string>"
  },
  "expected_output": "<string>",
  "agno_settings": {
    "session_storage": true,
    "user_memories": true,
    "session_summaries": true,
    "num_history_runs": 123,
    "max_tool_calls_from_history": 123,
    "tool_call_limit": 123,
    "coordinate_mode": true,
    "pii_detection_enabled": true,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": true,
    "openai_moderation_enabled": true,
    "openai_moderation_categories": [
      "<string>"
    ]
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": true,
  "is_generalist": true,
  "webhook_url": "<string>"
}
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
​
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, gpt-4o-mini)
​
should_reset_graph
boolean
Reset the agent’s graph (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": "Updated Agent Name",
    "instructions": {
      "role": ["You are a helpful assistant"],
      "goal": ["Help users with their questions"],
      "general": "Be concise and accurate"
    },
    "model_name": "gpt-4o"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}

​
Example Response

{
  "id": "e9aaf26b-5e8b-42ce-9a96-b32acd9136cb",
  "unique_name": "purple-caterpillar",
  "name": "Doc Test Agent",
  "icon": "📝",
  "avatar": "male-avatar",
  "status": "ACTIVE",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "deployment_type": "serverless",
  "framework": "agno",
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "type": "manager",
  "delegation_type": "router",
  "created_at": "2025-11-06T21:07:52.047275Z",
  "instructions": {
    "role": [],
    "goal": [],
    "general": "Test agent for documentation"
  },
  "tools": [],
  "knowledge_bases": [],
  "deletable": true,
  "using_nemo": false,
  "version": 2
}

​
Notes

  • At least one field must be provided in the request body
  • Only the specified fields will be updated
  • Other fields remain unchanged
  • The agent may need to be redeployed after significant changes

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Body

application/json
​
organization_id
string | null

The organization id

​
agent_id
string | null

The id of the agent we want to apply the changes to

​
name
string | null

use only when need to update name of an agent

​
instructions
object | null

use only when need to update instructions of an agent

​
icon
string | null

use only when need to update icon (emoji) of an agent

​
should_reset_graph
boolean | null
default:false

Should reset graph of this agent?

​
model_provider
string | null
​
environment_id
string | null

Target environment id to create the agent in

​
model_name
string | null

Response

Successful Response

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
delegation_end_strategy
enum<string> | null
default:return-to-start

Enumeration of the agent delegation end strategies.

Attributes: ReturnToStart: when last agent is finished and about to announce "finish" it will summarize and return to the first agent. FinishWithLast: finish at the last agent.

Available options:
return-to-start,
finish-with-last
​
environment_id
string | null
​
sub_agents_continuous_thread
boolean | null
default:true
​
deployment_type
enum<string> | null
default:serverless
Available options:
serverless,
container
​
created_by_prompt
string | null
​
prompts
string[] | null
​
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:organizational
Available options:
personal,
organizational
​
instructions
object | null
​
oas
object | null
​
graph
AIAgentGraphItem · object[] | null
​
llm_settings
AIAgentGraphItemLLMSettings · 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.

Available options:
manager,
regular
​
delegation_type
enum<string> | null
default:router

Enumeration of the agent delegation types.

Attributes: Router: Marks the agent as a router agent - xpanderAI's LLM will decide which sub-agent to trigger. Sequence: Marks the agent as a sequence agent - sub-agents will delegate to other sub-agents.

Available options:
router,
sequence
​
delegation_memory_strategy
enum<string> | null
default:summarization

Enumeration of the agent delegation memory strategies.

Attributes: Full: The memory object will be passed completely between agents. Summarization: Between each sub-agent delegation, a summarization will occur, and a new thread will be created for each agent. OriginalInput: the sub agent will get the initial task with a fresh memory thread

Available options:
full,
summarization,
original-input
​
is_ai_employee
boolean | null
default:false
​
using_nemo
boolean | null
default:false
​
deletable
boolean | null
default:true
​
model_provider
enum<string> | null
default:openai
Available options:
openai,
nim,
amazon_bedrock,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks
​
model_name
string | null
default:gpt-4.1
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json
​
output_schema
object | null
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
object | null
​
expected_output
string | null
default:""
​
agno_settings
object | null
​
on_prem_event_streaming
boolean | null
default:true
​
prompts_caching_enabled
boolean | null
default:false
​
is_generalist
boolean | null
default:false