Create an Agent
Create an Agent. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state.
curl --request POST \
--url https://api.revoengine.com/api/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "On-call incident triage",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'On-call incident triage',
serviceAccountUserId: '11111111-1111-4111-8111-111111111111'
})
};
fetch('https://api.revoengine.com/api/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/agents"
payload = {
"name": "On-call incident triage",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"agentId": "99999999-9999-4999-8999-999999999999",
"name": "Release Reporter",
"status": "ACTIVE",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111",
"config": {
"model": "configured-model",
"maxTicks": 24
},
"policy": {
"maxTicks": 24,
"toolNames": [
"ref_search"
]
},
"createdBy": "44444444-4444-4444-8444-444444444444",
"createdAt": "2026-06-13T10:00:00.000Z",
"lastUpdateAt": "2026-06-13T10:15:00.000Z",
"lastUpdateBy": "44444444-4444-4444-8444-444444444444",
"version": 3,
"desc": "Summarizes release status and creates operator updates.",
"ownerId": "22222222-2222-4222-8222-222222222222",
"ownerType": "USER",
"rootStorageEntryId": "33333333-3333-4333-8333-333333333333",
"metadata": {
"team": "operations"
},
"avatar": "https://storage.example/avatar.png",
"summary": {
"activeRunCount": 1,
"queuedInboxCount": 3
}
}Authorizations
Bearer JWT token or API Key (sk-*).
Body
Stable display name of the agent.
1"On-call incident triage"
User id of the service account used as the execution principal.
"11111111-1111-4111-8111-111111111111"
Optional operator-facing description.
"Investigates production alerts and prepares escalation notes."
Owning user or group id used for visibility and management.
"22222222-2222-4222-8222-222222222222"
Owner type, typically USER or GROUP.
"USER"
Optional resource metadata. Values may use any JSON type. Maximum 16 KiB and 64 top-level keys. Top-level keys starting with "__" are reserved for backend use.
{ "costCenter": "ops" }
Persisted Agent identity and runtime defaults, including work mode, persona, instructions, memory policy, and execution limits.
Show child attributes
Show child attributes
{
"model": "configured-model",
"reasoningEffort": "medium",
"workMode": "operator",
"persona": "pragmatic",
"maxActiveRootRuns": 2,
"maxChildRuns": 4,
"maxConcurrentChildRuns": 2,
"maxTicks": 80
}
Persisted policy constraints such as tool allowlists, agent plugins, and delegation ceilings. Runtime-only route metadata is not configured here.
Show child attributes
Show child attributes
{
"toolNames": ["slack.send_message", "storage.read"],
"maxChildRuns": 4,
"maxConcurrentChildRuns": 2
}
Response
Stable agent id.
"99999999-9999-4999-8999-999999999999"
Agent display name.
"Release Reporter"
Agent lifecycle status.
ACTIVE, PAUSED, DISABLED "ACTIVE"
Service account user id used as execution principal.
"11111111-1111-4111-8111-111111111111"
Persisted agent runtime defaults and identity inputs.
{
"model": "configured-model",
"maxTicks": 24
}
Persisted execution constraints and role gates.
{
"maxTicks": 24,
"toolNames": ["ref_search"]
}
User id that created the agent.
"44444444-4444-4444-8444-444444444444"
Creation timestamp.
"2026-06-13T10:00:00.000Z"
Last update timestamp.
"2026-06-13T10:15:00.000Z"
User id that last updated the agent.
"44444444-4444-4444-8444-444444444444"
Optimistic locking version.
3
Operator-facing description.
"Summarizes release status and creates operator updates."
Owning user or group id.
"22222222-2222-4222-8222-222222222222"
Owner type, typically USER or GROUP.
"USER"
Agent workspace root storage entry id.
"33333333-3333-4333-8333-333333333333"
Resource metadata.
{ "team": "operations" }
Signed avatar URL, when an avatar is configured.
"https://storage.example/avatar.png"
Per-agent operational summary when requested by list or overview endpoints.
Show child attributes
Show child attributes
{
"activeRunCount": 1,
"queuedInboxCount": 3
}
curl --request POST \
--url https://api.revoengine.com/api/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "On-call incident triage",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'On-call incident triage',
serviceAccountUserId: '11111111-1111-4111-8111-111111111111'
})
};
fetch('https://api.revoengine.com/api/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/agents"
payload = {
"name": "On-call incident triage",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"agentId": "99999999-9999-4999-8999-999999999999",
"name": "Release Reporter",
"status": "ACTIVE",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111",
"config": {
"model": "configured-model",
"maxTicks": 24
},
"policy": {
"maxTicks": 24,
"toolNames": [
"ref_search"
]
},
"createdBy": "44444444-4444-4444-8444-444444444444",
"createdAt": "2026-06-13T10:00:00.000Z",
"lastUpdateAt": "2026-06-13T10:15:00.000Z",
"lastUpdateBy": "44444444-4444-4444-8444-444444444444",
"version": 3,
"desc": "Summarizes release status and creates operator updates.",
"ownerId": "22222222-2222-4222-8222-222222222222",
"ownerType": "USER",
"rootStorageEntryId": "33333333-3333-4333-8333-333333333333",
"metadata": {
"team": "operations"
},
"avatar": "https://storage.example/avatar.png",
"summary": {
"activeRunCount": 1,
"queuedInboxCount": 3
}
}