Skip to main content
PUT
/
agents
/
{agentId}
Update Agent
curl --request PUT \
  --url https://api.example.com/agents/{agentId} \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "bio": "<string>",
  "lore": [
    {}
  ],
  "topics": [
    {}
  ],
  "adjectives": [
    {}
  ],
  "style": {},
  "settings": {},
  "plugins": [
    {}
  ],
  "enabled": true
}
'
{
  "success": true,
  "data": {
    "data.agentId": "<string>",
    "data.name": "<string>",
    "data.updatedAt": 123
  }
}

​
Endpoint

PUT /agents/{agentId}
Updates an existing agent’s character configuration, settings, or status. You can modify any aspect of the agent without recreating it.

​
Request

​
Path Parameters

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

​
Headers

​
Content-Type
string
required
Must be application/json
​
Authorization
string
Bearer token for authentication (if required)

​
Body Parameters

All parameters are optional. Only include fields you want to update.
​
name
string
New name for the agent’s character
​
bio
string
Updated biography or description
​
lore
array
Updated background story elements
​
topics
array
Updated list of topics
​
adjectives
array
Updated personality adjectives
​
style
object
Updated communication style settings
​
settings
object
Updated configuration settings
​
plugins
array
Updated list of enabled plugins
​
enabled
boolean
Enable or disable the agent

​
Response

​
success
boolean
required
Indicates if the update was successful
​
data
object
required
Updated agent details
​
data.agentId
string
required
Unique identifier for the agent (UUID)
​
data.name
string
required
Updated name of the agent
​
data.updatedAt
number
Unix timestamp when the agent was updated

​
Examples

​
Update Agent Name

curl -X PUT http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice 2.0"
  }'

​
Update Multiple Fields

curl -X PUT http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "bio": "An advanced AI assistant with enhanced capabilities",
    "topics": [
      "customer support",
      "technical troubleshooting",
      "product recommendations"
    ],
    "adjectives": [
      "expert",
      "efficient",
      "proactive"
    ]
  }'

​
Update Settings

curl -X PUT http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "model": "gpt-4-turbo",
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

​
Disable Agent

curl -X PUT http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

​
Response Example

​
Success Response

{
  "success": true,
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Alice 2.0",
    "updatedAt": 1709683200000
  }
}

​
Code Examples

​
JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const updates = {
  bio: "An advanced AI assistant",
  topics: ["customer support", "technical help"],
  adjectives: ["expert", "helpful"]
};

const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updates)
});

const { success, data } = await response.json();

if (success) {
  console.log(`Agent updated: ${data.name}`);
}

​
Python

import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"

updates = {
    "bio": "An advanced AI assistant",
    "topics": ["customer support", "technical help"],
    "adjectives": ["expert", "helpful"]
}

response = requests.put(
    f'http://localhost:3000/agents/{agent_id}',
    json=updates
)

data = response.json()

if data['success']:
    print(f"Agent updated: {data['data']['name']}")

​
TypeScript

interface UpdateAgentRequest {
  name?: string;
  bio?: string;
  lore?: string[];
  topics?: string[];
  adjectives?: string[];
  style?: Record<string, any>;
  settings?: Record<string, any>;
  plugins?: string[];
  enabled?: boolean;
}

interface UpdateAgentResponse {
  success: boolean;
  data: {
    agentId: string;
    name: string;
    updatedAt: number;
  };
}

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const updates: UpdateAgentRequest = {
  bio: "An advanced AI assistant",
  topics: ["customer support", "technical help"]
};

const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(updates)
});

const result: UpdateAgentResponse = await response.json();

​
Error Responses

​
404 Not Found

{
  "success": false,
  "error": "Agent not found"
}

​
400 Bad Request

{
  "success": false,
  "error": "Invalid agent ID format"
}

​
500 Internal Server Error

{
  "success": false,
  "error": "Failed to update agent"
}

​
Important Notes

If the agent is currently running, some changes may require restarting the agent to take effect. Consider stopping and restarting the agent after significant configuration changes.
Updating the agent’s model or embedding model may require re-processing existing memories and embeddings.

​
Next Steps

Get Agent

View updated agent details

Start Agent

Restart the agent with new configuration

Delete Agent

Remove the agent permanently

Build docs developers (and LLMs) love

Get started for freeTalk to us