Create Agent

Creates a new agent with optional tools, API tools, MCP servers, and frontend actions. Use this endpoint to set up a fully configured agent in a single request. Validation: All referenced tools,

POST /ai-agents/agent-builder/agents

Create Agent

cURL

curl --request POST \
  --url https://{appId}.api-{region}.cometchat.io/v3/ai-agents/agent-builder/agents \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "name": "<string>",
  "icon": "<string>",
  "description": "<string>",
  "tools": [
    "<string>"
  ],
  "apiTools": [
    "<string>"
  ],
  "mcpServers": [
    "<string>"
  ],
  "instruction": "<string>",
  "metaData": {},
  "model": "gpt-4o-mini",
  "modelMetaData": {
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "isActive": true
}
'

201

{
  "agent": {
    "uid": "agent-uuid-1234",
    "appId": "my-app-id",
    "name": "Support Agent",
    "icon": "https://example.com/icon.png",
    "isActive": true,
    "description": "A helpful support agent",
    "tools": [
      "gmail",
      "slack"
    ],
    "files": [],
    "websites": [],
    "otherKbIntegrations": [],
    "apiTools": [],
    "mcpServers": [],
    "frontendActions": [],
    "ragVersion": "v2",
    "lastMessageAt": null,
    "instruction": "You are a helpful assistant",
    "formattedInstruction": "You are a helpful assistant",
    "metaData": {},
    "model": "gpt-4o-mini",
    "modelMetaData": {},
    "createdAt": 1700000000000,
    "updatedAt": 1700000000000
  }
}

For the complete error reference, see Error Guide.

Authorizations

apikey · string · header · required

API Key (i.e. Rest API Key from the Dashboard).

Headers

chatApiVersion · string · default: v3.0

Chat API version. Defaults to v3.0.

Body

application/json

name · string · required

Name of the agent

icon · string

URL to the icon/avatar of the agent

description · string

Description of the agent

tools · string[]

Array of tool names available to this agent

apiTools · string[]

Array of API tool names available to this agent

mcpServers · string[]

Array of MCP server names available to this agent

instruction · string

Instructions for the agent behavior

metaData · object

Additional metadata for the agent

model · string · default: gpt-4o-mini

AI model to use for this agent

modelMetaData · object

Configuration metadata for the AI model

Show child attributes

isActive · boolean · default: true

Is the agent active?

Response

201 - application/json

Agent created successfully

agent · object

Show child attributes