Create or update an agent

Create a new agent or update an existing one.

• Create: Omit id from the request body. Requires org:manage_agents:create permission or org:admin role.
• Update: Include the agent’s id in the request body. Requires org:manage_agents:update permission or org:admin role.

Cloning an agent: There is no dedicated clone endpoint. To clone an agent, GET /agents to retrieve the original, modify the payload (e.g., change the name), and POST /agents without an id to create it as a new agent.

Tool schemas are automatically refreshed to match the latest platform definitions when saving.

POST /agents

cURL

create

curl --request POST \
  --url https://www.asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "model": "openai:gpt-4o",
  "systemPrompt": "You are a helpful customer support agent.",
  "conversationStarters": [
    "How can I help you today?"
  ],
  "stage": "development",
  "showInChat": true
}
'

200

success

{
  "id": 1,
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "logoUrl": null,
  "conversationStarters": [
    "How can I help you today?"
  ],
  "model": "openai:gpt-4o",
  "maxToolRoundtrips": 50,
  "systemPrompt": "You are a helpful customer support agent.",
  "tools": {},
  "mcpServers": null,
  "stage": "development",
  "showInChat": true,
  "emailSlug": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

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"

id · 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"

reasoningEffort · enum<string> | null

How hard the model reasons. Omit to leave unchanged; null uses the model's default. Rejected with 400 when the agent's model doesn't offer that level, including when you change model and the saved level doesn't fit the new one.

Available options: low, medium, high

Example:

"low"

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"

versionLabel · string

One-line note on what this save changes, shown in the agent's version history. Omit it and the note is generated from the changed fields. Ignored when the save changes no versioned config.

Maximum string length: 1000

Example:

"Added the pipeline report to the Monday summary"

tagIds · integer[]

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

Example:

[1, 2]

Response

200

application/json

Agent created or updated successfully

id · 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

The agent's model: a tier the org's current model fills (tier:economy, tier:standard, tier:premium), or a specific model identifier (e.g., anthropic:claude-sonnet-5-5)

Example:

"tier:standard"

currentModel · string | null

The model the agent runs today: for a tier, the org's current model for it; otherwise the same as model. Null when no connected provider can run it.

Example:

"anthropic:claude-sonnet-5-5"

reasoningEffort · enum<string> | null

Per-agent reasoning effort; null means the model's default.

Available options: low, medium, high

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

tags · object[]

Tags associated with this agent

Show child attributes