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>",
  "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>"
  },
  "role": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.pragmatiks.io/llms.txt

Use this file to discover all available pages before exploring further.

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.

Agent types live inside the tenant SurrealDB namespace — the namespace is the organization boundary, so the record itself carries no organization_id field.

Identity fields (frozen - immutable after creation): name: Machine-readable name unique within the namespace.

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.

Platform fields (system-managed): role: Optional platform role marker. "main_router" identifies the single entry-point agent for POST /agents/chat. None for user-created types.

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
​
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.

​
role
string | null