Skip to main content
POST
/
agents
/
types
Create Agent Type
curl --request POST \
  --url https://api.example.com/agents/types/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "display_name": "<string>",
  "provider": "<string>",
  "model": "<string>",
  "description": "<string>",
  "icon": "<string>",
  "temperature": 123,
  "context_window": 123,
  "system_instructions": "<string>",
  "mcp_servers": [
    "<string>"
  ],
  "builtin_tools": [
    "<string>"
  ],
  "default_plan_template": [
    "<string>"
  ],
  "agent_resource_id": "<string>",
  "runner_resource_id": "<string>",
  "conversation_routing": {
    "when": "<string>",
    "examples": [
      "<string>"
    ],
    "avoid": "<string>"
  }
}
'
{
  "name": "<string>",
  "organization_id": "<string>",
  "display_name": "<string>",
  "provider": "<string>",
  "model": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "description": "<string>",
  "icon": "<string>",
  "temperature": 123,
  "context_window": 123,
  "system_instructions": "<string>",
  "mcp_servers": [
    "<string>"
  ],
  "builtin_tools": [
    "<string>"
  ],
  "default_plan_template": [
    "<string>"
  ],
  "agent_resource_id": "<string>",
  "runner_resource_id": "<string>",
  "created_by": "<string>",
  "version": 1,
  "conversation_routing": {
    "when": "<string>",
    "examples": [
      "<string>"
    ],
    "avoid": "<string>"
  }
}

Body

application/json

Request body for creating an agent type.

Attributes: name: Machine-readable name unique within organization. display_name: Human-readable name shown in UI. description: Agent purpose and capabilities. icon: Icon identifier or URL. provider: LLM provider (e.g., "anthropic", "openai"). model: Model identifier (e.g., "claude-opus-4", "gpt-4"). temperature: Sampling temperature for generation. context_window: Maximum context window size in tokens. system_instructions: System prompt for the agent. mcp_servers: MCP server identifiers available to the agent. builtin_tools: Built-in tool identifiers available to the agent. default_plan_template: Default plan steps for new tasks. agent_resource_id: SurrealDB resource ID for the agent type. runner_resource_id: SurrealDB resource ID for the runner resource. conversation_routing: Routing rules for conversation assignment.

​
name
string
required
​
display_name
string
required
​
provider
string
required
​
model
string
required
​
description
string | null
​
icon
string | null
​
temperature
number | null
​
context_window
integer | null
​
system_instructions
string | null
​
mcp_servers
string[]
​
builtin_tools
string[]
​
default_plan_template
string[] | null
​
agent_resource_id
string | null
​
runner_resource_id
string | null
​
conversation_routing
ConversationRoutingManifest · object

Routing rules for conversation-to-agent assignment.

Attributes: when: Natural language description of when this agent should handle a conversation. examples: Example messages that should route to this agent. avoid: Natural language description of messages this agent should not handle.

Response

Successful Response

Domain model for agent types with LLM configuration and tooling.

Identity fields (frozen - immutable after creation): name: Machine-readable name unique within organization. organization_id: Tenant that owns this agent type.

Configuration fields (mutable): display_name: Human-readable name shown in UI. description: Agent purpose and capabilities. icon: Icon identifier or URL. provider: LLM provider (e.g., "anthropic", "openai"). model: Model identifier (e.g., "claude-opus-4", "gpt-4"). temperature: Sampling temperature for generation. context_window: Maximum context window size in tokens. system_instructions: System prompt for the agent. mcp_servers: MCP server identifiers available to the agent. builtin_tools: Built-in tool identifiers available to the agent. default_plan_template: Default plan steps for new tasks. conversation_routing: Routing rules for conversation assignment.

Resource fields (linking to pragma resources): agent_resource_id: SurrealDB resource ID for the agent type. runner_resource_id: SurrealDB resource ID for the runner resource.

Audit fields: created_by: User ID of the creator. version: Schema version for migration support.

Inherited from PragmaModel: created_at: Creation timestamp (frozen). updated_at: Last update timestamp (mutable).

​
name
string
required
​
organization_id
string
required
​
display_name
string
required
​
provider
string
required
​
model
string
required
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
id
string | null
​
description
string | null
​
icon
string | null
​
temperature
number | null
​
context_window
integer | null
​
system_instructions
string | null
​
mcp_servers
string[]
​
builtin_tools
string[]
​
default_plan_template
string[] | null
​
agent_resource_id
string | null
​
runner_resource_id
string | null
​
created_by
string | null
​
version
integer
default:1
​
conversation_routing
ConversationRoutingManifest · object

Routing rules for conversation-to-agent assignment.

Attributes: when: Natural language description of when this agent should handle a conversation. examples: Example messages that should route to this agent. avoid: Natural language description of messages this agent should not handle.