Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://api.ag.dev/v0.1/agents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "modelStackId": "anthropic/default",
  "name": "<string>",
  "description": "<string>",
  "webhookUrl": "<string>",
  "inputSchema": {
    "type": "<string>",
    "properties": {},
    "required": [
      "<string>"
    ]
  },
  "goalPrompt": "<string>",
  "customPlanningInstructions": "<string>",
  "customToolCallInstructions": "<string>",
  "customResultInstructions": "<string>",
  "enableContextCompression": true,
  "tools": [
    {
      "source": "builtin",
      "type": "searchWeb"
    }
  ],
  "resultType": "document",
  "resultSchema": {
    "type": "<string>",
    "properties": {},
    "required": [
      "<string>"
    ]
  }
}'
{
  "id": "<string>",
  "modelStackId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "webhookUrl": "<string>",
  "inputSchema": {},
  "goalPrompt": "<string>",
  "customPlanningInstructions": "<string>",
  "customToolCallInstructions": "<string>",
  "customResultInstructions": "<string>",
  "enableContextCompression": true,
  "tools": [
    {
      "source": "builtin",
      "type": "searchWeb"
    }
  ],
  "resultType": "document",
  "resultSchema": {},
  "isActive": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
modelStackId
enum<string>
required

The model stack to use for the agent

Available options:
anthropic/default,
anthropic/default-next,
openai/default,
openai/reasoning,
openai/reasoning-low,
hybrid/reasoning-low
​
inputSchema
object
required

JSON schema defining the structure of input data for runs

​
goalPrompt
string
required

The main prompt that defines what the agent should accomplish

​
tools
object[]
required

List of tools available to the agent

Minimum length: 1
  • Option 1
  • Option 2
​
resultType
enum<string>
required

Type of result the agent should produce

Available options:
document,
json
​
name
string

Optional human-readable name for the agent

​
description
string

Optional human-readable description for the agent

​
webhookUrl
string<uri> | null

URL to receive webhook notifications when runs complete

​
customPlanningInstructions
string | null

Optional custom instructions for the planning phase

​
customToolCallInstructions
string | null

Optional custom instructions for tool calling

​
customResultInstructions
string | null

Optional custom instructions for result formatting

​
enableContextCompression
boolean
default:true

Whether to enable context compression when agent run becomes too long

​
resultSchema
object

JSON schema for result validation (required when resultType is 'json')

Response

Agent created successfully

​
id
string
required

Unique identifier for the agent

​
modelStackId
string
required

The model stack used by the agent

​
inputSchema
object
required

JSON schema defining input structure

​
goalPrompt
string
required

The main goal prompt for the agent

​
tools
object[]
required

Available tools for the agent

  • Option 1
  • Option 2
​
resultType
enum<string>
required

Type of result the agent produces

Available options:
document,
json
​
isActive
boolean
required

Whether the agent is active

​
createdAt
string<date-time>
required

Agent creation timestamp

​
updatedAt
string<date-time>
required

Agent last update timestamp

​
name
string | null

Human-readable name for the agent

​
description
string | null

Human-readable description for the agent

​
webhookUrl
string<uri> | null

Webhook URL for run completion notifications

​
customPlanningInstructions
string | null

Custom planning instructions

​
customToolCallInstructions
string | null

Custom tool call instructions

​
customResultInstructions
string | null

Custom result formatting instructions

​
enableContextCompression
boolean

Whether context compression is enabled

​
resultSchema
object | null

JSON schema for result validation (only for json result type)