Deployments.ai Docs
Agents

Create an agent definition

POST /v1/agent-definitions · SDK createAgentDefinition · CLI deployments agent create

POST
/v1/agent-definitions

Authorization

platformBearer
headerAuthorizationBearer <token>

Platform bearer credential accepted as an opaque API key or JWT.

Header Parameters

x-deployments-environment*string
Match^[0-7][0-9A-HJKMNP-TV-Z]{25}$
idempotency-key*string
Length1 <= length <= 512

Request Body

application/json
  1. body
manifest*
workspaceId?string

Active workspace in the environment that owns the definition. The slug must be unique in that workspace. Set only on create.

Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$

Response Body

AgentDefinitionResponse

application/json
  1. response
createdAt*string
Match^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
Formatdate-time
updatedAt*string
Match^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
Formatdate-time
version*integer
Range0 <= value <= 9007199254740991
environmentId*string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
organizationId*string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
projectId*string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
id*string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
name*string
slug*string
status*string
Value in"active""archived"
workspaceId?string

Workspace that owns the definition. Absent for a definition shared by the environment.

Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
draft*
curl -X POST "https://example.com/v1/agent-definitions" \  -H "x-deployments-environment: string" \  -H "idempotency-key: string" \  -H "Content-Type: application/json" \  -d '{    "manifest": {      "apiVersion": "agents.deployments.ai/v1",      "kind": "Agent",      "metadata": {        "key": "string",        "name": "string",        "version": "string"      },      "spec": {        "instructions": "string",        "model": {          "id": "string"        },        "sandbox": {          "mode": "none"        }      }    }  }'
{  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "version": 0,  "environmentId": "string",  "organizationId": "string",  "projectId": "string",  "id": "string",  "name": "string",  "slug": "string",  "status": "active",  "workspaceId": "string",  "draft": {    "apiVersion": "agents.deployments.ai/v1",    "kind": "Agent",    "metadata": {      "key": "string",      "name": "string",      "version": "string"    },    "spec": {      "agents": [        {          "agentKey": "string",          "awaitResult": true,          "description": "string",          "edgeKind": "delegation",          "key": "string",          "required": true        }      ],      "capabilities": {        "tools": [          {            "authorization": "none",            "name": "string",            "required": true,            "requiredScopes": [              "string"            ]          }        ]      },      "instructions": "string",      "memory": {        "mode": "agent",        "reviewMode": "auto-approve",        "transcriptPrivacy": "omit"      },      "model": {        "fallbackIds": [          "string"        ],        "id": "string",        "options": {          "promptCache": "system",          "provider": {            "allowFallbacks": true,            "only": [              "string"            ],            "order": [              "string"            ]          },          "reasoningEffort": "low"        }      },      "runtime": {        "modelTools": [          "string"        ],        "contextCheckpointMode": "auto",        "ingressAttachments": "attach",        "maxModelGenerations": 1,        "maxToolCalls": 1,        "modelInputTokenBudget": 1024,        "modelOutputTokenReserve": 1,        "modelToolProtocol": "gemma4",        "recentMessageCharacterBudget": 1,        "responseDepthPolicy": {          "classifierInstructions": "string",          "defaultInstructions": "string",          "defaultMaximumWords": 1,          "detailedInstructions": "string",          "minimumWords": 1,          "maximumWords": 1        },        "responseFormat": {          "type": "json_schema",          "name": "string",          "schema": {            "property1": null,            "property2": null          }        },        "toolRequests": [          {            "effect": "execute",            "idempotencyKey": "string",            "input": {              "property1": null,              "property2": null            },            "inputSummary": "string",            "requiredScopes": [              "string"            ],            "toolName": "string"          }        ],        "toolResultImages": "screenshots"      },      "platformSkills": [        "app-builder"      ],      "sandbox": {        "accessPolicyRef": "string",        "imageRef": "string",        "minMemoryMiB": 1,        "minVcpu": 1,        "mode": "none",        "poolKey": "string",        "provider": "aws_lambda_microvm"      },      "skills": [        "string"      ],      "triggers": [        "api"      ]    }  }}