Skip to main content
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.
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 — 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 — fetch a single agent by agentId or definition id
  • GET /api/v3/agents/{agentId}/card — getAgentCard — 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):
  • GET /api/v3/agents/{agentId}/configuration — getAgentConfiguration — the configuration the Console’s agent detail page shows
  • GET /api/v3/agents/{agentId}/readiness — getAgentReadiness — the agent’s “Ready to run” report
  • GET /api/v3/agents/{agentId}/setup-request — getAgentSetupRequest — the agent’s open setup request, if any
  • GET /api/v3/agent-templates — listAgentTemplates — the platform-wide agent templates
  • GET /api/v3/agents/{agentId}/procedure-grants — listAgentProcedureGrants — the procedures granted to or denied to the agent
  • GET /api/v3/agents/{agentId}/grants — listAgentGrants — the agent’s tool grants, tool-set rows and permitted capability set
  • GET /api/v3/agents/{agentId}/relationships — getAgentRelationships — who and what the agent is connected to
  • GET /api/v3/agents/{agentId}/knowledge-activity — listAgentKnowledgeActivity — the knowledge cases it recently authored and cited
  • GET /api/v3/agents/{agentId}/readable-scopes — listAgentReadableScopes — 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 — create an agent your App owns
  • PATCH /api/v3/agents/{agentId} — updateAgent — partial update of an agent your App owns; a platform or Personal key reaches the same operation as agent administration
  • DELETE /api/v3/agents/{agentId} — deleteAgent — 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 — grant a workspace tool set to an agent your App owns
  • POST /api/v3/agents/{agentId}/unassign-tool-set — unassignAgentToolSet — revoke your App’s grant of a tool set
  • POST /api/v3/agents/{agentId}/assign-skill — assignAgentSkill — grant a workspace skill, optionally overriding its activation mode
  • POST /api/v3/agents/{agentId}/unassign-skill — unassignAgentSkill — revoke your App’s grant of a skill
Permanent deletion (External App credentials with the opt-in agents:manage scope only; see Permanent deletion):
  • POST /api/v3/agents/{agentId}/delete-permanently — deleteAgentPermanently — permanently delete an archived agent your App owns
Versions, consumers and rollback (see Versions and rollback):
  • GET /api/v3/agents/{agentId}/versions — listAgentVersions — an agent’s immutable versions, newest first
  • GET /api/v3/agents/{agentId}/consumers — listAgentConsumers — the published workflow versions that pin the agent
  • POST /api/v3/agents/{agentId}/reinstate-version — reinstateAgentVersion — 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, for any credential that holds the key at the agent’s home (see Agent administration):
  • POST /api/v3/agents/{agentId}/pause — pauseAgent — pause an active agent (switches:use)
  • POST /api/v3/agents/{agentId}/resume — resumeAgent — resume a paused agent (switches:use)
  • POST /api/v3/agents/{agentId}/terminate — terminateAgent — terminate an agent (switches:use)
  • POST /api/v3/agents/{agentId}/assign-owner — assignAgentOwner — assign the accountable owner (agents:manage)
  • POST /api/v3/agents/{agentId}/acknowledge-review — acknowledgeAgentReview — acknowledge the owner review (agents:manage)
  • POST /api/v3/agents/{agentId}/attest-identity — attestAgentIdentity — attest the agent’s identity, as a person (agents:manage)
  • POST /api/v3/agents/{agentId}/request-setup — requestAgentSetup — ask for the agent’s missing setup (agents:read, 20 an hour)
  • POST /api/v3/agents/create-from-template — createAgentFromTemplate — create a draft agent from a template (agents:manage and agents:write)
  • POST /api/v3/agents/{agentId}/assign-procedure — assignAgentProcedure — grant a procedure you can read (agents:manage)
  • POST /api/v3/agents/{agentId}/unassign-procedure — unassignAgentProcedure — revoke a procedure grant (agents:manage)
  • POST /api/v3/agents/{agentId}/assign-tool — assignAgentTool — grant an active tool (agents:manage)
  • POST /api/v3/agents/{agentId}/unassign-tool — unassignAgentTool — revoke a tool grant (agents:manage)
  • POST /api/v3/agents/{agentId}/replace-exemplars — replaceAgentExemplars — replace a worker agent’s exemplars (agents:write)
Delegated work (see Delegated work):
  • GET /api/v3/agent-task-runs — listAgentTaskRuns — the sub-agent tasks agents dispatched, newest first
  • GET /api/v3/agent-consultations — listAgentConsultations — 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. 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 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 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 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 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), 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:
Promote a draft to active by partial update (this needs switches:use), then verify: