Skip to main content
POST
JavaScript
A variation starts with a model and a prompt and nothing to do. An assignment hands it a capability.

Exactly one target

The body is a discriminated union. type names the variant, and the matching key carries the ID. Set two keys and the request fails before it touches the database:
Assigning a tool set is the durable choice. It tracks the provider: tools discovered on a later sync appear to the agent without another assignment. Assigning toolId pins the agent to exactly the tools you name, which is what you want when a tool set is broad and the agent’s job is narrow.

Assign once

A target already on the variation is a 409, with the reason spelled out:
So a setup script that reruns catches 409 rather than assuming idempotency, unlike publish, which is a no-op the second time.

Nothing stops a sub-agent loop

An agent can be assigned as its own sub-agent, and two agents can be assigned to each other. Both return 200. There is no cycle check.
An agent that delegates to itself spawns a sub-objective that delegates again. Every node in that tree is a billed model run. Check the target before you assign it. The API does not.
The same endpoint rejects a duplicate tool set and a two-key union, so the validation gap is specific to the shape of the sub-agent graph, not to assignments in general.

What the agent sees

Publish the agent, and the next objective’s tool list carries every assigned tool. In the event stream, toolCalled.tool names which kind was called. It is a discriminated union, so narrow on type:
Assignments are not paged. There is no GET .../assignments collection (it returns 415). Read them from the variation:
Remove one by its avt_... id:

Memory is a different call

Memory layers are not assignments. They have their own route and their own ordering, because the cascade resolves keys by position:
Assigning any memory layer is what gives the agent get_memory and search_memory.

Search tools and tool sets

Find the ID to assign. It returns the same three kinds.

Delegate to sub-agents

What subAgentId buys you, and how a sub-objective reports back.

Preventing tool bloat

When to assign one tool instead of a whole set.

Publish an agent

Assignments go live on the next objective, with no republish.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

agentId
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

variationId
string
required

Variation ID. Accepts the canonical agentvar_… form or the external_id:<value> form.

Example:

"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"

Body

application/json

Attach a single tool, tool set, or sub-agent to a variation. Exactly one of the target fields must be set; the assignment kind is inferred from the populated field.

type
enum<string>
required
Available options:
toolId
toolId
string
required
Example:

"tool_01HXKD2E5NQM3T9AYWCFWVYY9K"

Response

OK

A read-only reference to a single tool, tool set, or sub-agent attached to a variation. Read the full set of assignments via AgentVariationInfo.assignments; mutations go through the dedicated add/remove assignment endpoints.

The id identifies the assignment itself (not the referenced resource) and is the handle used to remove the assignment. It is returned by the add endpoint and present on every entry in AgentVariationInfo.assignments.

type
enum<string>
required
Available options:
tool
tool
object
required

BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.

id
string
read-only
Example:

"avt_01HXKD2E5NQM3T9AYWCFJE6K89"