---
url: /handbook/agents/agent-builder.md
description: >-
  The agent builder workspace, how each field is filled and limited, and what a
  saved manifest holds.
---

# Agent builder and manifests

The agent builder turns a proposed agent into a saved manifest. It opens already filled from the Company Repo. The advisor reviews it, can only make it tighter, and saves a version.

## The workspace

Select **Agents**. The builder opens on the last agent you opened, or the first proposed agent.

| Area | What it holds |
| --- | --- |
| **Top bar** | **Your team** (each person with a proposed agent, and their agents), the draft's version and freshness, **Save draft** and **Download .zip** |
| **Authority** line | Acts for, owner, limit, the steps where it pauses, and the authority check |
| **Left** | Seven sections you open and close: **Agent config**, **Instructions**, **Tools and connectors**, **Context**, **Human gates**, **Tests** and **Handoffs**. |
| **Right** | The export files, with your unsaved changes applied, one tab per format, and **Copy** |
| **Before it can run** | The readiness checks and gaps (none blocks the draft), **Governed access** and **Share the plan with `<person>`** |

## Where each value comes from

Every filled field has a provenance chip, such as "from check-supplier-packet/task.md › Rule". Select it to open the Repo file.

* A field you changed and did not save reads "Edited by you · was: …".
* A saved change reads "Edited by `<name>` · Repo value: …". It has no Repo chip, because a person wrote it.
* **Use the Repo value** puts the Repo value back. Save to keep it.
* In **Agent config**, **Raw** shows the exact Repo file, read only. **Rendered** goes back.

**Acts for**, **Owner**, **Proposed** and **Limit by rule** come from the Repo and cannot be changed here. DutyGraph does not choose a model: it shows "Not set · the client chooses" until you pick one.

## Steps and markers

**Instructions** lists the Task Card steps, word for word. Code gives each step a marker:

| Marker | Meaning |
| --- | --- |
| `[A]` | The agent may do the step. |
| `[S]` | The step needs a recorded approval from a person. |
| `[H]` | A person does the step. |

A step code cannot classify is `[H]`. You can tighten a marker (A → S → H), never loosen it. To change a step's text, edit the Task Card. **Notes for the agent** adds your own words; the steps and markers still win.

### Limit by rule

Code caps the AI mode. Risk lowers the mode. It never raises it.

| When a step… | The limit is at most |
| --- | --- |
| contacts someone outside the company | AI drafts for review |
| handles money or bank details, or changes access | AI recommends, a person decides |
| needs an approval (`[S]`) | AI acts after a person approves |

## Tools and access

**Tools and connectors** has one card per system the Repo records. Each card shows what the steps need, the person's recorded access and one state: **Within access**, **Outside access** or **Access: Not found**.

Each tool operation has a policy: **Allow**, **Auto within set limits**, **Ask first** or **Off**. "Auto within set limits" exists only when the limit is "AI acts within set limits". A looser policy than code allows is not offered. Its tooltip says why, for example "The limit is set by the person's access."

* **Access editor:** record the role's access to the system (No access, Read, Write or Admin) and its source. **Reported** is the default. **Client confirmed** needs the client's answer to the access ask. DutyGraph records the level only. It does not change access in the system.
* **Request access** drafts an ask to the person who grants access to that system. On **Access: Not found**, the button reads **Ask** and that person's name. Nothing is sent automatically.
* DutyGraph holds no credential. The card names the person who provides it.

**Human gates** names the person at each `[H]` or `[S]` step. **Tests** holds cases code makes from stop conditions, labelled "Case from a stop condition · not a past case". **Context** lists only Repo files the person's role may read. **Handoffs** are context only.

## Save a draft

**Save draft** makes a new version when the manifest changes: "Saved as v2 · 8 Oct 2026. The draft gives no access." If nothing changed, the version stays.

DutyGraph saves nothing when:

* a marker or policy is looser than code allows;
* another person saved after you opened it (reload first);
* a Task Card holds an email address, a phone number or a value that looks like a secret. The message names the Task Card and field.

A save never writes over a draft agent a person made by hand. It makes a new draft and lists the other as **Related draft**.

## Freshness

**Agents › Saved agents** compares each cited Repo file on every read. Freshness is about the manifest's sources. It does not change any issued authorization.

| State | Meaning | What to do |
| --- | --- | --- |
| **Fresh** | No cited file changed. | Nothing. |
| **Out of date** | A cited file changed, or an edit no longer matches a step. | **Show changes**, review each field, save again. |
| **Broken** | A cited file was removed or withdrawn, a cited person left, or the person's access dropped. | Review and save again. Until then, only the sheet and JSON export. |

## A draft is not an authorization

A saved manifest is the agent's definition and the source of its implementation files. It is not its authorization. "The draft gives no access" holds for every version.

* Authority comes only from a governed request that the [approval chain](../governance/approval-chain.md) approves and IAM issues.
* **Within access** on a tool card means the recorded access level covers what the steps need. It is a ceiling check, not proof that the access is needed or approved.
* A material change to the manifest after issue should be checked again against the issued authorization. Freshness flags source changes today. Linking a changed manifest to its issued agent for revalidation is **Planned**.

## Not proposed

**Opportunities › Proposed agents** lists what code did not turn into an agent, with one reason and an ask.

| Reason | Meaning |
| --- | --- |
| No accountable owner | Nobody owns the work. |
| Conflicting accounts | People describe the work differently. |
| People only | The Task Card has no proposed AI mode. |
| AI not allowed | The Task Card does not allow AI. |
| Route: a change that is not an agent | Route chose a cheaper change first. |

**Draft the ask** opens the ask in the Discovery composer. Nothing is sent until you send it.

| Field | What it holds |
| --- | --- |
| `schema`, `id`, `version` | `dutygraph.agent-manifest.v1`, the `AGT-…` id, and the version (+1 on every saved change) |
| `actsFor`, `owner` | The person the agent acts for, and the accountable owner, with their roles |
| `duties`, `taskCards` | The duties and Task Cards, each pinned by record version and content hash |
| `systemsAccess` | Each system and the role's access level and source |
| `proposedMode`, `autonomyCeiling`, `ceilingReasons` | The proposed AI mode, the limit by rule, and why |
| `steps`, `humanGates` | Each step with its marker and system; who acts at each gate |
| `tools` | Each system's operations, their policies, the authority check and who provides the credential |
| `instructions`, `notesForAgent` | The compiled instructions; a person's added notes |
| `stopConditions`, `denied` | When to stop; what it must never do |
| `context`, `handoffs` | Repo files the role may read; handoffs as context |
| `tests`, `pastCases` | Cases from stop conditions; past cases found of 3 needed |
| `notFound` | Every gap, with the person to ask. Never filled in. |
| `provenance` | The Repo fingerprint, each cited file and hash, and `manifestHash`. `approval` is always empty. |
| `lifecycle` | Always `proposed` |

::: info
**Status.** **Built:** the workspace, provenance chips, markers, limit rules, tool policies, the access editor, versioned saves, freshness and Not proposed reasons. **Simulated:** access values on the sample companies, labelled "Reported · sample". **Planned:** describing an agent in words, past cases from people, recorded approvals inside the manifest, and revalidating an issued authorization when its manifest changes.
:::
