> 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/developer-guide/platform-api/functions/agent-definitions.md).

# Agent Definitions

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.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

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.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions/validate" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## List Definitions

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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Get a Definition

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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions/{definition\_id}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Get a Definition Version

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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions/{definition\_id}/versions/{version}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Archive a Definition

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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/agent-definitions/{definition\_id}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}


---

# 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/developer-guide/platform-api/functions/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.