> ## 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.

# Ship an audited agent

> End-to-end recipe — from a fresh agent definition to a Convex-native dispatch with every tool call, every governance decision, and every token spend recorded in the audit trail.

This recipe creates a workspace Worker agent, grants only the capabilities it needs, runs it through a workflow, and verifies the evidence Forge actually records. Audit coverage is path-specific: governance decisions, model usage, tool execution, and workflow results have related but distinct records. Verification is therefore part of shipping, not an assumption.

## The end state

When the recipe is done:

* The agent definition has a stable `agentId`, `name`, `agentType: "WORKER"`, prompt, model configuration, and governance classification.
* A unique active `workers` row pairs the agent with the organization; dispatch refuses an invalid or ambiguous pairing.
* Skill and tool-set grants live in canonical assignment tables, while context-bound tools such as `file_get`, `file_put`, `load_skill`, and `sandbox_action` are injected only by eligible dispatch sites.
* A test workflow completes with an expected `stepResults` record, a governance decision, and the tool/model evidence relevant to the path you exercised.

## Prerequisites

* An External App token to create the agent, with `agents:write` and `agents:read` at the app's owning org unit. The create call this recipe uses, `POST /api/v3/agents`, accepts only an External App token. Activating it needs `switches:use` at the platform.
* Console access to finish the agent's **Ready to run** checklist (owner, position and identity) and to publish the test workflow.
* A [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or platform API key with `workflows:use` to dispatch the test workflow and `workflows:read` where the run lives to read its audit packet. The audit packet refuses an External App token.

## The four steps

SHIP AN AUDITED AGENT

<ol aria-label="SHIP AN AUDITED AGENT" />

**1. Define the agent**

Create a workspace agent through **Workforce → Agents → New**. Platform-shipped system agents are source-controlled fixtures and are not an appropriate starting point for an operator recipe. The persisted contract is component-owned; the public create body (`POST /api/v3/agents`) takes these fields:

```ts theme={null}
{
  agentId: "contract-summarizer",
  name: "Contract Summarizer",
  description: "Extracts named commercial terms from an authorized contract file.",
  purpose: "Produce a reviewable structured summary; never approve or sign.",
  model: { default: "anthropic/claude-sonnet-4-6", allowOverride: false },
  prompt: { core: "Summarize only the supplied contract. Cite the source page for each term." },
  status: "active",
}
```

The create body carries no grants, governance or constraints: set skill and tool-set grants, the governance tier (worker, personal, or system, not a numeric autonomy level) and constraints in Console. The independent autonomy rung is one of `assistive`, `retrieval`, `supervised`, or `bounded` and is managed by the agent controls that enforce rung transitions. Seat the Worker agent in the org chart and confirm exactly one active AGENT worker points at the definition before testing dispatch.

**2. Bind skills and tools**

Skills provide reusable instructions; tool sets grant static capabilities. Forge records each grant as its own skill or tool-set assignment on the agent and resolves them at dispatch through [agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition). They are not lists stored inside the agent definition.

For this recipe, author a workspace skill (use `contract-summarizer-system` for this example) in **Platform → Skills → Create**, or with `POST /api/v3/skills`, then activate it. See [Skill Authoring](https://docs.gloo.com/forge/build/author-a-skill.md) for the three authoring paths and the review a skill passes before activation.

Select the narrowest live sets shown by **Platform → Tools** and the [`TOOL_SETS` reference](https://docs.gloo.com/forge/reference/tool-sets). Do not invent a `READ_ONLY` set. A workflow node with a declared file input/output receives bound `file_get` and `file_put` tools from the dispatch context; those tools cannot be granted through an assignment.

```ts theme={null}
toolSets: ["runAnalysis"],
skills: ["contract-summarizer-system", "extract-key-terms"],
```

Expected result: the agent detail shows the two skill grants and only the selected static tool set. The test workflow additionally advertises `file_get` / `file_put` because its node contract authorizes file input/output. A grant narrows the tool surface; it does not prove the prompt, external system, or data itself is safe. Trust Fabric decisions, credential scope, file bindings, and provider controls remain independent boundaries.

**3. Wire governance and budgets**

Choose an autonomy rung from the action profile you intend to allow. `retrieval` is appropriate for a summarizer that reads bounded inputs and returns a result; `supervised` or `bounded` is relevant only when the agent performs controlled writes. Do not map command tiers (Tier 1 typed catalog commands and Tier 3 free-form sandbox commands) onto agent autonomy—they are different contracts.

If the agent must always pause for review before running, attach an [approval policy](https://docs.gloo.com/forge/run/approvals-and-hitl.md) to the agent or the workflow node that dispatches it. The `hold` disposition that the `approvalRequired` gate records when the policy matches is what creates the row in `approvals` — see the [approval lifecycle flow](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle) for the state machine.

Attach the applicable [budget](https://docs.gloo.com/forge/run/budgets-and-cost.md) through the budget surface and add an [approval policy](https://docs.gloo.com/forge/run/approvals-and-hitl.md) if this workflow must pause. There is no `defaultBudgetUsd` field on the agent definition. Run preflight and confirm the intended policy and envelope are selected before launch.

**4. Observe what it did**

Launch a workflow that supplies one non-sensitive test contract and declares one structured summary output. Verify each system in its own operator surface:

* **Run detail:** the node reaches the expected terminal status and its `stepResults` row identifies the agent, model used, timing, and output.
* **Trust Fabric decisions:** the launch/dispatch decision shows the real subject and disposition; a hold is released only through the linked approval.
* **Tool activity:** `file_get` reads only the input file ID, and `file_put` binds the result to the declared output key.
* **Cost and audit views:** token/cost records and lifecycle/configuration events appear where that path emits them. Do not claim a single `auditEvents` row is the universal store for all four kinds of evidence.

Recovery: if the run is refused, start from the governance explanation and worker pairing. If file access is refused, compare the workflow node's declared file inputs/outputs with the concrete file IDs and output key. If the model differs, inspect the node override, routing decision, and active catalog status before changing the agent.

## Do it over the API

These calls use the `FORGE_BASE` and `ACCESS_TOKEN` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). The two ends need different credentials: creating the agent accepts only an External App token, and reading the audit packet refuses one, so read it with a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or a platform API key. The HTTP create takes the identity, model and prompt fields; set skill and tool-set grants, governance and constraints in Console.

Create the agent. This call accepts only an External App token, and the app owns the agent:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/agents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-contract-summarizer-v1" \
  -d '{"agentId": "contract-summarizer", "name": "Contract Summarizer", "description": "Extracts named commercial terms from an authorized contract file.", "purpose": "Produce a reviewable structured summary; never approve or sign.", "model": {"default": "anthropic/claude-sonnet-4-6", "allowOverride": false}, "prompt": {"core": "Summarize only the supplied contract. Cite the source page for each term."}}' \
  | jq '.data'
```

This needs `agents:write` and `agents:read` at the app's owning org unit; an unknown field is `400`. The agent is created as a draft. Activate it, which also gives it the worker that runs its steps; a status change needs `switches:use` at the platform:

```bash theme={null}
curl -sS -X PATCH "$FORGE_BASE/api/v3/agents/contract-summarizer" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: activate-contract-summarizer-v1" \
  -d '{"status": "active"}' | jq '.data'
```

An agent the app creates has no owner, position or attested identity yet. Before publishing the test workflow, finish its setup on the agent's **Ready to run** checklist in Console; see [Check that an agent is ready to run](https://docs.gloo.com/forge/console/workforce/agents#check-that-an-agent-is-ready-to-run). After the test workflow is published, dispatch it (use your workflow's name and add `runtimeArgs` matching its inputs), which needs `workflows:use`:

```bash theme={null}
RUN_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-summarizer-test-run-v1" \
  -d '{"name": "contract-summarizer-test"}' \
  | jq -r '.data.runId')
```

Read the run's audit packet, which needs `workflows:read` where the run lives:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/runs/$RUN_ID/audit-packet" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {disposition, approvals, headline: .explanation.headline}'
```

[Audit](https://docs.gloo.com/forge/run/audit.md) explains each field of the packet.

Over MCP, dispatch with `forge_call_operation`:

```json theme={null}
{ "operationId": "dispatchWorkflow", "input": { "name": "contract-summarizer-test" }, "idempotencyKey": "contract-summarizer-test-run-v1" }
```

and read the packet with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "getRunAuditPacketAdmin", "input": { "runId": "<run id>" } }
```

## When to reach for something else

* **You want the agent to act outside the workflow graph.** Chat, factory, copilot, and PA dispatch sites all run governance and write audit, but they are conversational rather than DAG-driven. Use a workflow when you need retry, checkpoint, or HITL approval; use chat when you need a back-and-forth with a human in a session.
* **You only need a local experiment.** Prototype outside a production workflow, then bring it into Forge when you need governed identity, durable execution, and operator evidence.
* **You need the agent to persist working memory across sessions.** Add a [memory configuration](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) — the three-layer model (session, channel, long-term) handles continuity without expanding the audit surface.


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