> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/agent-definitions.md).

# Agent Definitions

## GET /v1/{workspace\_id}/agent-definitions

> List Agent Definitions

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AgentDefinitionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentDefinitionSummary"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"AgentDefinitionListResponse"},"AgentDefinitionSummary":{"properties":{"definition_id":{"type":"string","format":"uuid","title":"Definition Id"},"name":{"type":"string","title":"Name"},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"status":{"type":"string","enum":["active","archived"],"title":"Status"}},"type":"object","required":["definition_id","name","framework","status"],"title":"AgentDefinitionSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions":{"get":{"tags":["Agent Definitions"],"summary":"List Agent Definitions","operationId":"list_agent_definitions_v1__workspace_id__agent_definitions_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"framework","in":"query","required":false,"schema":{"anyOf":[{"enum":["claude-agent-sdk","openai-agents"],"type":"string"},{"type":"null"}],"title":"Framework"}},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Archived"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDefinitionListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/agent-definitions

> Register Agent Definition

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisterAgentDefinitionRequest":{"properties":{"name":{"$ref":"#/components/schemas/SlugString","description":"Stable slug identifying this definition within the workspace."},"body":{"additionalProperties":true,"type":"object","title":"Body","description":"The framework-native definition document (its 'framework' field selects the shape). Validated by the platform clamp schema — a non-whitelisted field is rejected."}},"type":"object","required":["name","body"],"title":"RegisterAgentDefinitionRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"RegisterAgentDefinitionResponse":{"properties":{"definition_id":{"type":"string","format":"uuid","title":"Definition Id"},"version":{"type":"integer","title":"Version"},"created":{"type":"boolean","title":"Created","description":"False when an identical body was already registered (idempotent push)."},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"has_write_tools":{"type":"boolean","title":"Has Write Tools"},"agent_count":{"type":"integer","title":"Agent Count"},"body_sha256":{"type":"string","title":"Body Sha256"}},"type":"object","required":["definition_id","version","created","framework","has_write_tools","agent_count","body_sha256"],"title":"RegisterAgentDefinitionResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions":{"post":{"tags":["Agent Definitions"],"summary":"Register Agent Definition","operationId":"register_agent_definition_v1__workspace_id__agent_definitions_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentDefinitionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentDefinitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Validate Agent Definition

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisterAgentDefinitionRequest":{"properties":{"name":{"$ref":"#/components/schemas/SlugString","description":"Stable slug identifying this definition within the workspace."},"body":{"additionalProperties":true,"type":"object","title":"Body","description":"The framework-native definition document (its 'framework' field selects the shape). Validated by the platform clamp schema — a non-whitelisted field is rejected."}},"type":"object","required":["name","body"],"title":"RegisterAgentDefinitionRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"ValidateAgentDefinitionResponse":{"properties":{"valid":{"type":"boolean","const":true,"title":"Valid"},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"has_write_tools":{"type":"boolean","title":"Has Write Tools"},"agent_count":{"type":"integer","title":"Agent Count"}},"type":"object","required":["valid","framework","has_write_tools","agent_count"],"title":"ValidateAgentDefinitionResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions/validate":{"post":{"tags":["Agent Definitions"],"summary":"Validate Agent Definition","description":"Dry-run clamp validation — nothing is stored. 422 with the offending\npaths on failure (the same shape push returns).","operationId":"validate_agent_definition_v1__workspace_id__agent_definitions_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentDefinitionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAgentDefinitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## GET /v1/{workspace\_id}/agent-definitions/{definition\_id}

> Get Agent Definition

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AgentDefinitionDetail":{"properties":{"definition_id":{"type":"string","format":"uuid","title":"Definition Id"},"name":{"type":"string","title":"Name"},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"status":{"type":"string","enum":["active","archived"],"title":"Status"},"versions":{"items":{"$ref":"#/components/schemas/AgentDefinitionVersionMeta"},"type":"array","title":"Versions"}},"type":"object","required":["definition_id","name","framework","status","versions"],"title":"AgentDefinitionDetail"},"AgentDefinitionVersionMeta":{"properties":{"version":{"type":"integer","title":"Version"},"body_sha256":{"type":"string","title":"Body Sha256"},"validator_rev":{"type":"string","title":"Validator Rev"},"has_write_tools":{"type":"boolean","title":"Has Write Tools"},"agent_count":{"type":"integer","title":"Agent Count"}},"type":"object","required":["version","body_sha256","validator_rev","has_write_tools","agent_count"],"title":"AgentDefinitionVersionMeta"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions/{definition_id}":{"get":{"tags":["Agent Definitions"],"summary":"Get Agent Definition","operationId":"get_agent_definition_v1__workspace_id__agent_definitions__definition_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"definition_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Definition Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDefinitionDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/agent-definitions/{definition\_id}

> Archive Agent Definition

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions/{definition_id}":{"delete":{"tags":["Agent Definitions"],"summary":"Archive Agent Definition","operationId":"archive_agent_definition_v1__workspace_id__agent_definitions__definition_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"definition_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Definition Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/agent-definitions/{definition\_id}/versions/{version}

> Get Agent Definition Version

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AgentDefinitionVersionDetail":{"properties":{"version":{"type":"integer","title":"Version"},"body_sha256":{"type":"string","title":"Body Sha256"},"validator_rev":{"type":"string","title":"Validator Rev"},"has_write_tools":{"type":"boolean","title":"Has Write Tools"},"agent_count":{"type":"integer","title":"Agent Count"},"definition_id":{"type":"string","format":"uuid","title":"Definition Id"},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"body":{"additionalProperties":true,"type":"object","title":"Body"}},"type":"object","required":["version","body_sha256","validator_rev","has_write_tools","agent_count","definition_id","framework","body"],"title":"AgentDefinitionVersionDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-definitions/{definition_id}/versions/{version}":{"get":{"tags":["Agent Definitions"],"summary":"Get Agent Definition Version","operationId":"get_agent_definition_version_v1__workspace_id__agent_definitions__definition_id__versions__version__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"definition_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Definition Id"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDefinitionVersionDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/agent-definitions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.