Agent Definitions

Register, version, validate, and manage native agent definitions within a workspace.

The Agent Definitions API lets you register, version, retrieve, and archive customer-authored, framework-native agent configurations. Native agent runs reference a definition by ID and version.

Key Concepts

• Definition head: The workspace-scoped identity of a definition, identified by a stable name and framework. A name must be unique among active definitions in a workspace.
• Definition version: An immutable snapshot of the definition body. Every push of a changed body mints a new version number. Re-pushing identical content returns the existing version.
• Clamp validation: The definition body is validated against a strict whitelist schema. Unrecognized fields are validation errors rather than silently ignored input.
• Framework lock: A definition's framework cannot change after registration. Archive the existing definition before reusing its name with another framework.
• Soft archive: Archiving marks a definition inactive and frees its name for reuse. Existing versions remain immutable and readable.

Supported Frameworks

Framework	Description
openai-agents	A declarative handoff graph of agents with an entry point and handoff routing
claude-agent-sdk	A single agent with optional subagents and a system prompt

Permissions

Operation	Required Permission	Minimum Role
Register or validate	Service create	Member
List or get	Service view	Viewer
Archive	Service delete	Admin

Register a Definition

Registers a definition or appends a version to an existing definition with the same name and framework. An identical canonical body is idempotent and returns the existing version.

Register Agent Definition

post

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

namestring · min: 2 · max: 63Required

Stable slug identifying this definition within the workspace.

Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Responses

200

Successful Response

application/json

definition_idstring · uuidRequired

versionintegerRequired

createdbooleanRequired

False when an identical body was already registered (idempotent push).

frameworkstring · enumRequiredPossible values:

has_write_toolsbooleanRequired

agent_countintegerRequired

body_sha256stringRequired

422

Validation Error

application/json

post/v1/{workspace_id}/agent-definitions

POST /v1/{workspace_id}/agent-definitions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "name": "text",
  "body": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "definition_id": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "created": true,
  "framework": "claude-agent-sdk",
  "has_write_tools": true,
  "agent_count": 1,
  "body_sha256": "text"
}

A name collision with another framework returns 409 Conflict. Clamp validation failures return 422 Unprocessable Entity with the offending field paths.

Validate a Definition

Runs the same clamp validation as registration without storing the definition.

Validate Agent Definition

post

Dry-run clamp validation — nothing is stored. 422 with the offending paths on failure (the same shape push returns).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

namestring · min: 2 · max: 63Required

Stable slug identifying this definition within the workspace.

Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Responses

200

Successful Response

application/json

validconst: Required

frameworkstring · enumRequiredPossible values:

has_write_toolsbooleanRequired

agent_countintegerRequired

422

Validation Error

application/json

post/v1/{workspace_id}/agent-definitions/validate

POST /v1/{workspace_id}/agent-definitions/validate HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "name": "text",
  "body": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "valid": true,
  "framework": "claude-agent-sdk",
  "has_write_tools": true,
  "agent_count": 1
}

List Definitions

Returns definition heads newest first and supports filtering archived definitions and frameworks.

List Agent Definitions

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

frameworkstring · enum · nullableOptionalPossible values:

include_archivedbooleanOptionalDefault: false

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/agent-definitions

GET /v1/{workspace_id}/agent-definitions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "definition_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "framework": "claude-agent-sdk",
      "status": "active"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get a Definition

Returns a definition head and version metadata without returning every version body.

Get Agent Definition

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

definition_idstring · uuidRequired

Responses

200

Successful Response

application/json

definition_idstring · uuidRequired

namestringRequired

frameworkstring · enumRequiredPossible values:

statusstring · enumRequiredPossible values:

422

Validation Error

application/json

get/v1/{workspace_id}/agent-definitions/{definition_id}

GET /v1/{workspace_id}/agent-definitions/{definition_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "definition_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "framework": "claude-agent-sdk",
  "status": "active",
  "versions": [
    {
      "version": 1,
      "body_sha256": "text",
      "validator_rev": "text",
      "has_write_tools": true,
      "agent_count": 1
    }
  ]
}

Get a Definition Version

Returns one immutable version, including its framework-native definition body.

Get Agent Definition Version

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

definition_idstring · uuidRequired

versionintegerRequired

Responses

200

Successful Response

application/json

versionintegerRequired

body_sha256stringRequired

validator_revstringRequired

has_write_toolsbooleanRequired

agent_countintegerRequired

definition_idstring · uuidRequired

frameworkstring · enumRequiredPossible values:

422

Validation Error

application/json

get/v1/{workspace_id}/agent-definitions/{definition_id}/versions/{version}

GET /v1/{workspace_id}/agent-definitions/{definition_id}/versions/{version} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "version": 1,
  "body_sha256": "text",
  "validator_rev": "text",
  "has_write_tools": true,
  "agent_count": 1,
  "definition_id": "123e4567-e89b-12d3-a456-426614174000",
  "framework": "claude-agent-sdk",
  "body": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Archive a Definition

Soft-archives the active definition and frees its name for reuse without deleting its versions.

Archive Agent Definition

delete

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

definition_idstring · uuidRequired

Responses

204

Successful Response

No content

422

Validation Error

application/json

delete/v1/{workspace_id}/agent-definitions/{definition_id}

DELETE /v1/{workspace_id}/agent-definitions/{definition_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content