Create or update an agent

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

name

string

required

Agent name

Example:

"Customer Support Agent"

integer

Agent ID — include to update an existing agent, omit to create a new one

Example:

1

description

string

Short description of the agent's purpose

Example:

"Handles customer inquiries and support tickets"

logoUrl

string

URL to the agent's logo image

conversationStarters

string[]

Suggested conversation starters shown to users

Example:

[
  "How can I help you today?",
  "What issue are you experiencing?"
]

model

string

Model identifier (e.g., openai:gpt-4o, anthropic:claude-sonnet-4-20250514)

Example:

"openai:gpt-4o"

maxToolRoundtrips

integer

Maximum number of tool call roundtrips per response

Required range: x >= 1

Example:

50

systemPrompt

string

System prompt / instructions for the agent

Example:

"You are a helpful customer support agent. Be friendly and concise."

tools

object

Tool definitions keyed by tool name (e.g., scrape_url, search_knowledge_base). Two shapes are accepted:

Native tools: { description, parameters } — copy these from GET /tools. Schemas are refreshed to the latest platform definitions on save.
Provider tools (e.g., google:code_execution): { "isProviderTool": true } keyed under the provider:tool name.

Per-tool config (e.g., callableAgentIds for call_agent, accessibleKnowledgeBaseIds for search_knowledge_base) can be set under a config field and is preserved by POST /agents/sync-tools.

Call GET /tools to discover the names and parameter shapes available to the org.

integrations

string[]

List of enabled integration identifiers

mcpServers

integer[]

List of MCP server IDs to connect (integer mcp_server.id values)

stage

enum<string>

default:development

Agent lifecycle stage

Available options:

development,

released

showInChat

boolean

default:true

Whether the agent appears in the chat interface

emailSlug

string | null

Custom email slug for the agent's email address. Must be lowercase alphanumeric with hyphens, cannot start or end with a hyphen, max 63 characters. Must be unique across all agents. Cannot use reserved slugs (admin, support, help, noreply, postmaster, etc.) and cannot match the agent-{id} or kb-{id} system patterns.

Maximum string length: 63

Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$

Example:

"support-bot"

tagIds

integer[]

Tag IDs to associate with this agent (must belong to the organization)

Example:

[1, 2]

Response

Agent created or updated successfully

integer

required

Unique agent identifier

Example:

1

name

string

required

Agent name

Example:

"Customer Support Agent"

stage

enum<string>

required

Agent lifecycle stage

Available options:

development,

released

Example:

"development"

showInChat

boolean

required

Whether the agent appears in the chat interface

Example:

true

createdAt

string<date-time>

required

When the agent was created

Example:

"2024-01-15T10:30:00.000Z"

updatedAt

string<date-time>

required

When the agent was last updated

Example:

"2024-01-20T14:00:00.000Z"

description

string | null

Short description of the agent's purpose

Example:

"Handles customer inquiries and support tickets"

logoUrl

string | null

URL to the agent's logo image

conversationStarters

string[] | null

Suggested conversation starters shown to users

Example:

[
  "How can I help you today?",
  "What issue are you experiencing?"
]

model

string | null

Model identifier (e.g., openai:gpt-4o)

Example:

"openai:gpt-4o"

maxToolRoundtrips

integer | null

Maximum number of tool call roundtrips per response

Example:

50

systemPrompt

string | null

System prompt / instructions for the agent

tools

object | null

Tool definitions keyed by tool name

mcpServers

integer[] | null

Connected MCP server IDs (integer mcp_server.id values)

emailSlug

string | null

Custom email slug for the agent's email address

Example:

"support-bot"

publishedVersionId

integer | null

ID of the agent_version snapshot this agent's config currently reflects. Every save appends a version and advances this pointer; see GET /agents/versions. The live agent fields above remain the source of truth — this is bookkeeping for history and rollback.

Example:

42