Assign a tool, tool set, or sub-agent
Give a variation a capability. One call, one target: a single tool, a whole tool set, or another agent.
Exactly one target
The body is a discriminated union.type names the variant, and the matching key carries the ID.
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 a409, with the reason spelled out:
409 rather than assuming idempotency, unlike publish, which is a no-op the second time.
Nothing stops a sub-agent loop
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:
GET .../assignments collection (it returns 415). Read them from the variation:
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:get_memory and search_memory.
Related
Search tools and tool sets
Delegate to sub-agents
subAgentId buys you, and how a sub-objective reports back.Preventing tool bloat
Publish an agent
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Variation ID. Accepts the canonical agentvar_… form or the external_id:<value> form.
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"
Body
- Option 1
- Option 2
- Option 3
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.
Response
OK
- Option 1
- Option 2
- Option 3
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.
tool 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.
"avt_01HXKD2E5NQM3T9AYWCFJE6K89"