> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Author, fetch, and manage agent definitions through the Platform API.

`agents/listDeployments`, `agents/deploy`, and `agents/undeploy` were removed on 2026-09-30. They had been retired earlier, when deployment records were removed: `listDeployments` answered `200` with an empty list and the other two answered `501`. They now answer the router's `404`. Deployment state lives on the agent record itself via `status`; composition happens at dispatch time through `composeAgentConfig`.

Agents are the unit of work in Forge. An agent definition combines a prompt, a permitted set of skills and tools, a model, and governance metadata. External integrations use the Agents domain to discover the agents available to them and to author or update the ones owned by their App.

## Visibility

Every agent read returns only agents your key or External App may read: it must hold `agents:read` at the agent's home org unit, or at an org unit above it. An agent with no home org unit is never returned, and PERSONAL agents are never returned. An agent an External App creates is homed at the App's owning org unit, so the App reads it there. An agent an App created before 2026-10-01 stays homed at the deployment root and is returned only when the App holds `agents:read` there. An agent you may not read answers `404 resource_missing`, the same as a missing one.

## Resource shape

* `Agent` — exactly `id`, `agentId`, `name`, `description`, `purpose`, `version`, `status`, `owner`, `ownedByCaller`, `tags`, `executionModel`, `model`, `governance`, `createdAt`, and `updatedAt`. Every field is present: `purpose`, `version`, `owner`, `executionModel`, `model`, and `governance` are `null` when unset, and `tags` is `[]`. `model` carries `default`, `allowOverride`, and `constraints` (`minContextWindow`, `minTier`); `governance` carries `tier` and `dataScope`.
* `AgentCard` — the Agent-to-Agent (A2A) discovery card: `a2aVersion` (`"0.2"`), `name`, `description`, `url`, `provider`, `version`, `capabilities` (streaming and push notifications are always `false`), `skills` (each `id` and `name`), `inputModes`, `outputModes`, and `authentication`.

Both schemas are explicit allowlists and reject other fields. Prompts, files, memory, constraints, tools, subagents, identity and its attestation, the home org unit, the stored principal, and internal fields are not returned. Use `ownedByCaller`, not `owner`, to tell whether your App created an agent.

> [!NOTE]
>
> Forge agents are Convex-native — there is no separate deployment step. Composition happens at dispatch time via `composeAgentConfig`, so a status change takes effect on the next dispatch.

## Lifecycle

Every agent moves through a status lifecycle: `draft` → `active` → optionally `inactive` or `deprecated`, and eventually `archived`. The `status` filter on `listAgents` lets external systems target a specific stage.

## Operations

Reads:

* `GET /api/v3/agents` — [listAgents](https://docs.gloo.com/forge/reference/http-api/agents/list.md) — one page of the agents you may read, oldest first, optionally searched and filtered by status, execution model and tier
* `GET /api/v3/agents/{agentId}` — [getAgent](https://docs.gloo.com/forge/reference/http-api/agents/get.md) — fetch a single agent by `agentId` or definition id
* `GET /api/v3/agents/{agentId}/card` — [getAgentCard](https://docs.gloo.com/forge/reference/http-api/agents/getCard.md) — fetch the A2A discovery card for an agent

One agent's detail, grants, relationships and knowledge, and the template gallery (see [One agent's detail](#one-agent’s-detail)):

* `GET /api/v3/agents/{agentId}/configuration` — [getAgentConfiguration](https://docs.gloo.com/forge/reference/http-api/agents/getConfiguration.md) — the configuration the Console's agent detail page shows
* `GET /api/v3/agents/{agentId}/readiness` — [getAgentReadiness](https://docs.gloo.com/forge/reference/http-api/agents/getReadiness.md) — the agent's "Ready to run" report
* `GET /api/v3/agents/{agentId}/setup-request` — [getAgentSetupRequest](https://docs.gloo.com/forge/reference/http-api/agents/getSetupRequest.md) — the agent's open setup request, if any
* `GET /api/v3/agent-templates` — [listAgentTemplates](https://docs.gloo.com/forge/reference/http-api/agents/listTemplates.md) — the platform-wide agent templates
* `GET /api/v3/agents/{agentId}/procedure-grants` — [listAgentProcedureGrants](https://docs.gloo.com/forge/reference/http-api/agents/listProcedureGrants.md) — the procedures granted to or denied to the agent
* `GET /api/v3/agents/{agentId}/grants` — [listAgentGrants](https://docs.gloo.com/forge/reference/http-api/agents/listGrants.md) — the agent's tool grants, tool-set rows and permitted capability set
* `GET /api/v3/agents/{agentId}/relationships` — [getAgentRelationships](https://docs.gloo.com/forge/reference/http-api/agents/getRelationships.md) — who and what the agent is connected to
* `GET /api/v3/agents/{agentId}/knowledge-activity` — [listAgentKnowledgeActivity](https://docs.gloo.com/forge/reference/http-api/agents/listKnowledgeActivity.md) — the knowledge cases it recently authored and cited
* `GET /api/v3/agents/{agentId}/readable-scopes` — [listAgentReadableScopes](https://docs.gloo.com/forge/reference/http-api/agents/listReadableScopes.md) — the knowledge scopes it reads

`listAgents` is paged: `limit` (1–100, default 50) and `cursor`. Follow `meta.nextCursor` while `meta.hasMore` is `true`. `limit` counts the agents returned, after visibility and filters; a short page is either the last one (`meta.hasMore` is `false`) or one that examined its limit of 200 agents and stopped (`meta.hasMore` is `true`). `search` (a substring of the slug, name, description or purpose), `executionModel` and `tier` filter as the Console's agents page does.

Writes (External App credentials; for create and archive any other credential is `403 forbidden`):

* `POST /api/v3/agents` — [createAgent](https://docs.gloo.com/forge/reference/http-api/agents/create.md) — create an agent your App owns
* `PATCH /api/v3/agents/{agentId}` — [updateAgent](https://docs.gloo.com/forge/reference/http-api/agents/admin/update.md) — partial update of an agent your App owns; a platform or Personal key reaches the same operation as [agent administration](#agent-administration)
* `DELETE /api/v3/agents/{agentId}` — [deleteAgent](https://docs.gloo.com/forge/reference/http-api/agents/delete.md) — archive an agent your App owns

Tool-set and skill assignments (External App credentials with the opt-in `agents:manage` scope only):

* `POST /api/v3/agents/{agentId}/assign-tool-set` — [assignAgentToolSet](https://docs.gloo.com/forge/reference/http-api/agents/assignToolSet.md) — grant a workspace tool set to an agent your App owns
* `POST /api/v3/agents/{agentId}/unassign-tool-set` — [unassignAgentToolSet](https://docs.gloo.com/forge/reference/http-api/agents/unassignToolSet.md) — revoke your App's grant of a tool set
* `POST /api/v3/agents/{agentId}/assign-skill` — [assignAgentSkill](https://docs.gloo.com/forge/reference/http-api/agents/assignSkill.md) — grant a workspace skill, optionally overriding its activation mode
* `POST /api/v3/agents/{agentId}/unassign-skill` — [unassignAgentSkill](https://docs.gloo.com/forge/reference/http-api/agents/unassignSkill.md) — revoke your App's grant of a skill

Permanent deletion (External App credentials with the opt-in `agents:manage` scope only; see [Permanent deletion](#permanent-deletion)):

* `POST /api/v3/agents/{agentId}/delete-permanently` — [deleteAgentPermanently](https://docs.gloo.com/forge/reference/http-api/agents/deletePermanently.md) — permanently delete an archived agent your App owns

Versions, consumers and rollback (see [Versions and rollback](#versions-and-rollback)):

* `GET /api/v3/agents/{agentId}/versions` — [listAgentVersions](https://docs.gloo.com/forge/reference/http-api/agents/listVersions.md) — an agent's immutable versions, newest first
* `GET /api/v3/agents/{agentId}/consumers` — [listAgentConsumers](https://docs.gloo.com/forge/reference/http-api/agents/listConsumers.md) — the published workflow versions that pin the agent
* `POST /api/v3/agents/{agentId}/reinstate-version` — [reinstateAgentVersion](https://docs.gloo.com/forge/reference/http-api/agents/admin/reinstate-version.md) — roll an agent back to a prior version: an External App with `agents:manage` for an agent it owns, or a platform or Personal key as [agent administration](#agent-administration)

Agent administration, for any credential that holds the key at the agent's home (see [Agent administration](#agent-administration)):

* `POST /api/v3/agents/{agentId}/pause` — [pauseAgent](https://docs.gloo.com/forge/reference/http-api/agents/pause.md) — pause an active agent (`switches:use`)
* `POST /api/v3/agents/{agentId}/resume` — [resumeAgent](https://docs.gloo.com/forge/reference/http-api/agents/resume.md) — resume a paused agent (`switches:use`)
* `POST /api/v3/agents/{agentId}/terminate` — [terminateAgent](https://docs.gloo.com/forge/reference/http-api/agents/terminate.md) — terminate an agent (`switches:use`)
* `POST /api/v3/agents/{agentId}/assign-owner` — [assignAgentOwner](https://docs.gloo.com/forge/reference/http-api/agents/assignOwner.md) — assign the accountable owner (`agents:manage`)
* `POST /api/v3/agents/{agentId}/acknowledge-review` — [acknowledgeAgentReview](https://docs.gloo.com/forge/reference/http-api/agents/acknowledgeReview.md) — acknowledge the owner review (`agents:manage`)
* `POST /api/v3/agents/{agentId}/attest-identity` — [attestAgentIdentity](https://docs.gloo.com/forge/reference/http-api/agents/attestIdentity.md) — attest the agent's identity, as a person (`agents:manage`)
* `POST /api/v3/agents/{agentId}/request-setup` — [requestAgentSetup](https://docs.gloo.com/forge/reference/http-api/agents/requestSetup.md) — ask for the agent's missing setup (`agents:read`, 20 an hour)
* `POST /api/v3/agents/create-from-template` — [createAgentFromTemplate](https://docs.gloo.com/forge/reference/http-api/agents/createFromTemplate.md) — create a draft agent from a template (`agents:manage` and `agents:write`)
* `POST /api/v3/agents/{agentId}/assign-procedure` — [assignAgentProcedure](https://docs.gloo.com/forge/reference/http-api/agents/assignProcedure.md) — grant a procedure you can read (`agents:manage`)
* `POST /api/v3/agents/{agentId}/unassign-procedure` — [unassignAgentProcedure](https://docs.gloo.com/forge/reference/http-api/agents/unassignProcedure.md) — revoke a procedure grant (`agents:manage`)
* `POST /api/v3/agents/{agentId}/assign-tool` — [assignAgentTool](https://docs.gloo.com/forge/reference/http-api/agents/assignTool.md) — grant an active tool (`agents:manage`)
* `POST /api/v3/agents/{agentId}/unassign-tool` — [unassignAgentTool](https://docs.gloo.com/forge/reference/http-api/agents/unassignTool.md) — revoke a tool grant (`agents:manage`)
* `POST /api/v3/agents/{agentId}/replace-exemplars` — [replaceAgentExemplars](https://docs.gloo.com/forge/reference/http-api/agents/replaceExemplars.md) — replace a worker agent's exemplars (`agents:write`)

Delegated work (see [Delegated work](#delegated-work)):

* `GET /api/v3/agent-task-runs` — [listAgentTaskRuns](https://docs.gloo.com/forge/reference/http-api/agents/listTaskRuns.md) — the sub-agent tasks agents dispatched, newest first
* `GET /api/v3/agent-consultations` — [listAgentConsultations](https://docs.gloo.com/forge/reference/http-api/agents/listConsultations.md) — the questions agents asked other agents, newest first

### One agent's detail

Eight reads open one agent the way the Console's agent detail page does, and a ninth lists the template gallery.

* **Who.** The per-agent reads (`getConfiguration`, `getReadiness`, `getSetupRequest` and the five AR-2 reads below) need `agents:read` at the agent's home, the same rule as `get`: a missing, PERSONAL, unhomed or unreadable agent is one `404 resource_missing`. An unavailable agent store is `500`, never `404`. `listTemplates` needs `agents:read` at the platform scope, since templates are platform-wide; a grant only at an org unit is a recorded `403`.
* **Configuration.** The identity, model and fallback chain, prompt, run limits, external inference controls, memory settings, and the skills and tool sets the agent holds (granted minus denied, by natural key). Never its LLM-proxy key, owner, user or creator ids, attestation, files, embeddings, synthesis request or exemplars.
* **Readiness.** Each check's outcome, gate and message, and the kind of fix that clears it. Never the person, worker, seat, Job or definition hash a fix would use: people make those fixes in the Console.
* **Setup request.** Which gaps it asks people to fix and how many people it asks, never who; `data` is `null` when none is open or the agent is ready now.
* **Grants.** Procedure grants (a name only where you hold `workflows:read` at the procedure's home), a page at a time (`limit` 1–200, default 200; continue with `meta.nextCursor` while `meta.hasMore` is `true`; a page may be short while more remain), and tool grants, tool-set rows and the permitted capability set by natural key (500 per list at most, with `meta.partial`).
* **Relationships.** The worker, position and Job where you hold `workforce:read` at the position's org unit, Access where you hold `grants:read` at the platform scope, and each workflow that uses the agent where you hold `workflows:read` at its home; a part you may not read is named in `withheld`, hidden workflows are counted. The owner is only whether one is present and active.
* **Knowledge.** `listKnowledgeActivity` and `listReadableScopes` also need `knowledge:read` and return only knowledge your credential may read: unreadable cases are absent and unreadable scopes are counted.
* **Templates.** A name `search` (best match first), one `category`, or the whole gallery oldest first, a page at a time: `limit` 1–100 (default 50), and while `meta.hasMore` is `true`, `meta.nextCursor` as `cursor` with the same `search` and `category`. Neither list answers `meta.partial`. Never who created a template.

### Who may write which agent

The route permission `agents:write` is necessary, never sufficient. Each write decides authority at the agent's home, inside the write itself:

* **Create** homes the new agent at your App's owning org unit. Your App must be owned by an org unit and hold both `agents:write` and `agents:read` there; otherwise the answer is `403 forbidden` and nothing is written. The agent gets the worker role at that unit's company root. No other grant is created.
* **Update** and **delete** name the agent by its slug (`agentId`). This section covers an External App; a platform or Personal key updates an agent as [agent administration](#agent-administration). An agent your App may not read at its home is `404 resource_missing`, the same as a missing one. An agent your App does not own, or may not write at its home (`agents:write` there), is `403 forbidden`.
* **A status is an operator control.** A patch that carries `status` also needs `switches:use` given at the platform, as the Console's pause, resume and terminate do; a grant at an org unit is not enough. Without it the answer is `403`, and nothing is written: `permission_denied` when the credential holds `switches:use` nowhere, `forbidden` when it holds it only at an org unit. A same-key retry of a status change also needs `switches:use` then. `paused` pauses the agent, `active` activates a draft, and `deprecated` terminates it (not reversible). Each change records the same control audit entry the Console records, naming your App and who gave it `switches:use`. An agent never moves back to `draft` (`409 conflict`): pause or archive it instead. `delete` (archive) stays under `agents:write`.
* **Operator controls win.** The API never changes the status of an agent that is paused (`paused`), terminated (`deprecated`) or archived: that status change is `409 invalid_state` and nothing is written. That includes an agent your App paused. Its other fields stay editable. Resume a paused agent with [`resumeAgent`](https://docs.gloo.com/forge/reference/http-api/agents/resume) or in the Console.
* **Delete archives.** `DELETE /api/v3/agents/{agentId}` archives the agent and its versions, exactly as the Console's first remove does. Memory and knowledge are kept. Deleting an agent that is already archived is `409 invalid_state`: delete it permanently with `deleteAgentPermanently`.

Bodies are strict: an unknown field, a status outside the route's list (`draft` or `active` on create; `draft`, `active`, `paused` or `deprecated` on update), or a malformed `model` or `prompt` is `400 bad_request`. With an `Idempotency-Key`, a same-key retry returns the recorded result only while your App still owns the agent and may read it at its home; otherwise it is `409`. A companion API key is not idempotency-scoped.

### Tools and skills

An External App can give an agent it owns one workspace tool set or one skill at a time, and take back what it gave. The `agents:manage` scope is opt-in: the built-in Apps never carry it, and an operator grants it deliberately.

* **Who.** Only an External App, and only on an agent it owns. The App must hold `agents:manage` at the agent's home; `agents:write` does not stand in for it. An agent your App may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`.
* **What.** `toolSet` is a workspace tool set's `setId` (the `name` [listToolSets](https://docs.gloo.com/forge/reference/http-api/tools/listSets.md) returns), and `skillId` is a skill's slug. An unknown tool set or skill is `404 resource_missing`, and so is an assign of a tool set or skill that is not active. A system (builtin) tool set and a builtin or Anthropic skill are `409 conflict` in both directions: an operator assigns and revokes those in the Console.
* **Operator controls win.** When an operator denied a tool set or skill for the agent, assigning it is `409 conflict`; unassigning it never touches the deny, revokes your App's own grant if the deny masks one, and otherwise answers `changed: false`. The deny is never lifted or removed through the API. Your App only ever writes grants, and takes back only the grants it placed: unassigning a grant an operator placed, or changing its activation mode, is `409 conflict`.
* **Idempotent by state.** Each result names the agent definition (`id`), the agent slug, the target and whether it is now assigned. `changed` is `false` when the requested state already held, so nothing was written. On `assignSkill`, `activationMode` is the override now stored, or `null` when the skill's default applies; omitting it clears any earlier override.
* **Takes effect at once.** A change stale-marks the agent's dispatch configuration in the same write, so the next dispatch composes with it. Assignment is not execution authority: each tool the agent calls is still governed when it runs.

With an `Idempotency-Key`, a same-key retry returns the recorded result only while your App still owns the same agent definition and may read it at its home; otherwise it is `409`. Every change is audited with your App as the actor.

### Versions and rollback

Every change to an agent's definition mints an immutable version. A node of a published workflow version that pins an agent version runs exactly that version, so rolling the agent back or editing it never changes what that node runs. A node published before pinning (`pinnedVersion: null` in `listAgentConsumers`) has no version to run: in a published run it fails its step with `agent_version_missing`, inline or detached, until the workflow is republished; it never runs the agent's current definition. A draft run, which has no published version, composes the agent's current stored definition. Read the consumers before you change the agent.

* **Versions.** `listAgentVersions` returns `PrimitiveVersion` rows, newest first: `versionId`, `version`, `status`, `synthesisTier`, `createdAt`, and `active` / `canary`, which mark the versions the agent's heads point at. The prompt, model, grants snapshot and hashes are never returned. A page at a time (`limit` 1–100, default 100): continue while `meta.hasMore` is `true`, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may be short while more remain, and the list never answers `meta.partial`.
* **Consumers.** `listAgentConsumers` returns `PrimitiveConsumer` rows: one per node of a published workflow version that runs the agent, with `workflowId`, `workflowVersionId`, `workflowVersion`, `versionStatus` (`active` or `superseded`), `logicalNodeId` and `pinnedVersion` (`null` for a node published before pinning). A node is listed when it can run the agent: it has no worker assignment, it is assigned to a specific AGENT worker linked to this agent (or to one with no agent link), or its worker is chosen when the step runs by role or by AGENT worker kind, since the worker picked may run this agent. A node assigned to a person (a specific employee or contractor, the EMPLOYEE or CONTRACTOR worker kind, or an identity claim, which resolves to a person) or to another agent's specific worker is left out, and one whose assigned worker record cannot be read is left out with `meta.partial: true`. Drafts are never listed; `version=` keeps only nodes pinned to exactly that version. The credential's scopes must also include `workflows:read`, otherwise `403 permission_denied` naming it before anything is read; a workflow you may not read at its home is left out, and one whose home cannot be decided is left out with `meta.partial: true`. Paged with `limit` (1–50, default 50) and an opaque `cursor`; a page can be short or empty before the last one.
* **Rollback.** `reinstateAgentVersion` makes an exact prior version active again, as the Console's rollback does. It needs `agents:manage` at the agent's home. An External App may roll back only an agent it owns: an agent your App may not read is `404 resource_missing`; one it does not own, or without `agents:manage` there, is `403 forbidden`. A platform or Personal key reaches any agent, decided as [agent administration](#agent-administration) decides it. An agent an operator paused or terminated, or one that is archived, is `409 invalid_state`, as is a version the lifecycle cannot make active. A version the agent does not have is `404 resource_missing`; the version already active answers `headChanged: false` and nothing is written, so it does not discard a pending edit to the agent.
* **Attestation stays with people.** The API never attests the restored definition. The agent's identity attestation names the definition a person attested, so after a rollback it lapses until a person attests the agent again, in the Console or with [`attestAgentIdentity`](https://docs.gloo.com/forge/reference/http-api/agents/attestIdentity) and a Personal key, exactly as after an API edit.

An External App's body is strict: `id` (the agent's slug), `version`, and an optional `reason` of at most 500 characters, recorded in the version's history; the operation page shows a platform or Personal key's body. With an `Idempotency-Key`, an External App's same-key retry returns the recorded result only while the App still owns the same agent definition and may read it at its home; otherwise it is `409`. A platform or Personal key's same-key repeat does not run again and answers `409 idempotency_result_unavailable`. An External App's rollback runs with the App as the actor. Retiring or reinstating skill, tool and procedure versions stays in the Console.

### Permanent deletion

`deleteAgentPermanently` removes an archived agent for good, exactly as the Console's second remove does. It cannot be undone.

* **Who.** Only an External App, only on an agent it owns, with `agents:manage` held at the agent's home; `agents:write` does not stand in for it. An agent your App may not read at its home is `404 resource_missing`, the same as a missing one; one it does not own, or without `agents:manage` there, is `403 forbidden`.
* **Archive first.** Only an archived agent can be deleted permanently. Any other agent is `409 invalid_state` and nothing is written: archive it with `deleteAgent` first.
* **What is removed.** The agent definition is deleted, and its channel memory and the knowledge in its home namespace are purged in bounded batches that may finish after the response. Until the purge completes, the slug cannot be reused. Version rows stay as audit records, and published workflow versions keep their pins; `listAgentVersions` and `listAgentConsumers` answer `404` once the agent is gone.
* **Retries.** The body is strict: exactly `id`, the agent's slug. With an `Idempotency-Key`, a repeated key returns the recorded result while your App still holds `agents:manage` ([Stored-response replay](https://docs.gloo.com/forge/reference/idempotency.md#stored-response-replay)), and the delete never runs twice. Without a key, read the agent to learn an attempt's outcome: `404` means it is gone.

Publishing an agent for public A2A discovery stays a person decision in the Console; the API offers no route for it.

### Agent administration

The kill switch, the accountability repairs, the setup request and composition take any credential: a Personal key (acting as its owner, narrowed by its scopes), an External App or a platform API key, each decided at the agent's home with its own grants. The route's permission is necessary, never sufficient.

* **Who.** You need the route's permission at the agent's home org unit: `switches:use` for `pause`, `resume` and `terminate`; `agents:manage` for `assignOwner`, `acknowledgeReview`, `attestIdentity`, `reinstateAgentVersion` and the four grant routes; `agents:write` for `updateAgent` and `replaceExemplars`; `agents:read` for `requestSetup`. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing`; the permission missing at the home is a recorded `403 permission_denied`. For `updateAgent` and `reinstateAgentVersion`, a platform or Personal key holding the permission nowhere is a recorded `403`, and one holding it only at another org unit is a recorded `404 resource_missing`. `switches:use` is never held by a Forge agent.
* **The kill switch.** `pause` and `resume` move an agent between `active` and `paused`; `terminate` moves it to `deprecated`. Only an active agent can be paused and only a paused one resumed, so a terminated, archived or draft agent is never paused or resumed; an archived agent cannot be terminated. Each of these refusals is `409 invalid_state`. A call that changes nothing answers `changed: false` and writes no audit event. Each `reason` (8 to 1,000 characters) is audited with the key's owner or the App as the actor.
* **Accountability.** `assignOwner` and `acknowledgeReview` each start a new 90-day review window. Each takes the state you reviewed and refuses the write with `409 conflict` when the agent changed since; an agent with no active owner is `409 invalid_state`. Only a person can attest an identity: `attestIdentity` needs a Personal key. It attests only an approved definition: changes not yet approved are `409 invalid_state`. No person id or definition hash is returned.
* **Setup requests.** `requestSetup` opens one request for the agent's missing setup, reusing the open one while the same gaps remain. Each credential may ask 20 times an hour (`429 rate_limited` with `Retry-After`).
* **Composition.** `createFromTemplate` creates a draft agent at an External App's owning org unit, or at the org unit a Personal key names (default: its owner's home), and needs `agents:manage`, `agents:write` and `agents:read` there; a platform API key has no home and is refused. `assignProcedure` needs `procedures:read` at the procedure's home and a procedure grantable as an agent tool; `assignTool` needs an active tool and carries no overrides. Both write plain grants: an operator's deny is a `409 conflict` and stays in place on unassign. `replaceExemplars` replaces a worker agent's 2 to 5 exemplars, in a request of at most 256 KiB.
* **Retries.** With an `Idempotency-Key`, a repeat returns the recorded answer only while the slug names the same definition and you still may read the agent and hold the route's permission at its home (`agent_write`); otherwise it is `409`. A platform or Personal key's update or rollback is the exception: its same-key repeat does not run again and answers `409 idempotency_result_unavailable`.

### Delegated work

An agent can hand work to another agent: a **task run** dispatches a sub-agent (by id, by a capability query, or with inline instructions), and a **consultation** asks another agent a question. These two lists are the Console's delegated work page.

* **Who.** You need `agents:read` at the platform scope, the key and home the Console's page uses. A grant only at an org unit answers a recorded `403`.
* **Content follows the run.** A row's content (its label, its instructions or question, its capability query, its inputs, its result or answer, and its error) is returned only when the row's parent is a workflow run you can see: `runs:read` at the run's home and at every company it carries, as `GET /api/v3/runs/{runId}` decides it. Otherwise those fields are `null` and `contentWithheld` is `true`. A row whose parent is a chat always withholds them; chat content is read through the chat surface. Shown content is returned as recorded except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker.
* **What never crosses.** The parent chat session, worker ids, workpool jobs, the answer's agent thread, the audit trail, a task's tool sets, and a consultation's attachments (only `attachmentCount`).
* **Personal Agents stay out.** A row that names a PERSONAL agent, as the agent that dispatched or asked, the agent asked for, the agent that ran it or the agent consulted, is left out, so a page can hold fewer rows than `limit` while more remain.
* **Paging.** Rows come newest first, optionally filtered by `status`, a page at a time: `limit` 1–100 (default 50), and while `meta.hasMore` is `true`, `meta.nextCursor` as `cursor` with the same `status`. With `status`, `foreground` rows come before `background` rows, each newest first (the Console's order), so an older foreground row can come ahead of a newer background one. A row whose parent run cannot be decided within the request's limits withholds its content, as a run you cannot see does. Neither list answers `meta.partial`. An unavailable agent store answers `500`, never an empty list.
* **Not offered.** Cancelling, retrying or answering delegated work stays out of the API.

## Common workflow

Create a new agent and fetch its A2A discovery card:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/agents" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-triage-bot-1" \
  -d '{
    "agentId": "triage-bot",
    "name": "Triage Bot",
    "description": "Classifies inbound issues",
    "model": { "default": "anthropic/claude-sonnet-4-20250514" }
  }'

curl "$FORGE_BASE/api/v3/agents/triage-bot/card" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

Promote a draft to active by partial update (this needs `switches:use`), then verify:

```bash theme={null}
curl -X PATCH "$FORGE_BASE/api/v3/agents/triage-bot" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

curl "$FORGE_BASE/api/v3/agents/triage-bot" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Agents overview](https://docs.gloo.com/forge/build/define-an-agent.md) — conceptual background on agent definitions, prompts, and tools
* [Agent lifecycle](https://docs.gloo.com/forge/build/define-an-agent.md) — status states and transitions
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token
* [MCP Server — Discover before calling](https://docs.gloo.com/forge/reference/mcp-server.md#discover-before-calling) — the agent reads listed for AI agents; other agent operations go through `forge_call_operation`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.