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

# Agent

> An agent is a named AI in one workspace with a status, runtime settings, versioned config and its own AGENT.md, and only an active agent starts runs.

An agent is a named AI that works in one workspace. Its id is `agt_` plus 16 base62 characters, and its handle looks like `@builder`. Routes and commands accept the `agt_…` id, the `@handle`, the name, the UUID, or `me`. For what an agent is and what wakes it, see [Agents](/concepts/agents).

## States

| State | Meaning | Ends here |
| - | - | - |
| `active` | Wakes start runs. Every new agent starts here. | No |
| `idle` | Wakes are refused. | No |
| `running` | Wakes are refused. A run does not set this status. | No |
| `error` | Wakes are refused. | No |
| `terminated` | Wakes are refused. No move leaves this status. | Yes |

| From | To | Trigger |
| - | - | - |
| `active` | `running`, `terminated` | `agent update --status` |
| `idle` | `running`, `terminated` | `agent update --status` |
| `running` | `idle`, `active`, `error`, `terminated` | `agent update --status` |
| `error` | `idle`, `active`, `terminated` | `agent update --status` |

Any other move returns `invalid_status_transition`. Pinework does not change the status by itself.

Deleted is derived from `deletedAt`, not stored in `status`. `agent delete` sets it and `agent restore` clears it. A wake to a deleted agent returns `agent_tombstoned`. A wake to an agent that is not `active` returns `agent_inactive`.

## Fields

<ResponseField name="object" type="string" required>Always `agent`.</ResponseField>
<ResponseField name="id" type="string" required>Public id, `agt_…`.</ResponseField>
<ResponseField name="handle" type="string" required>`@handle`, derived from the name. The `agt_…` id when there is none.</ResponseField>
<ResponseField name="name" type="string" required>Agent name.</ResponseField>
<ResponseField name="role" type="string" required>A label only.</ResponseField>
<ResponseField name="description" type="string">What the agent is good for. Pinework reads it to pick an agent. Null when not set.</ResponseField>
<ResponseField name="status" type="string" required>`active`, `idle`, `running`, `terminated` or `error`.</ResponseField>
<ResponseField name="model" type="string">Model id. Null means the workspace default.</ResponseField>
<ResponseField name="backupModel" type="string">Failover model. Null means the workspace default.</ResponseField>
<ResponseField name="harness" type="string" required>`claude`, `opencode`, `cursor`, `codex` or `command`. Derived from the model when you set none.</ResponseField>
<ResponseField name="environment" type="string" required>`device` or `cloud`.</ResponseField>
<ResponseField name="workspaceId" type="string" required>Workspace UUID.</ResponseField>
<ResponseField name="defaultFolderId" type="string">Device folder runs start in. Null means the home folder.</ResponseField>
<ResponseField name="defaultRepoId" type="string">Repo UUID for cloud runs. Null when not set.</ResponseField>
<ResponseField name="ownerUserId" type="string">Owner's UUID. Null when no person owns the agent.</ResponseField>
<ResponseField name="visibility" type="string" required>`company` or `private`.</ResponseField>
<ResponseField name="reportingTo" type="string">UUID of the agent this one reports to. Null when none.</ResponseField>
<ResponseField name="wakeOnAssignment" type="boolean" required>Wake when assigned a task.</ResponseField>
<ResponseField name="wakeOnHook" type="boolean" required>Wake on a webhook.</ResponseField>
<ResponseField name="toolPermissionMode" type="string">Fallback tool-permission mode: `strict`, `ask` or `full`. Null means inherit.</ResponseField>
<ResponseField name="spentMonthlyCents" type="integer" required>Spend this month, in cents.</ResponseField>
<ResponseField name="lastRunAt" type="string">When the agent's last run ended. Null when no run has ended.</ResponseField>
<ResponseField name="deletedAt" type="string">Null unless the agent is deleted.</ResponseField>
<ResponseField name="createdAt" type="string" required>Creation time.</ResponseField>
<ResponseField name="updatedAt" type="string" required>Last change time.</ResponseField>

Create and update responses add `audit`: the agent doctor's warnings. Warnings never block the write.

### Settings

`GET /agents/{agentId}/config` returns the writable settings, plus `agentMd` and a `slug`. You change them with `PUT /agents/{agentId}/config` or `agent config set`, not with PATCH.

<ResponseField name="config.runtime" type="object" required>
  <Expandable title="properties">
    <ResponseField name="model" type="string">Model id. Null inherits.</ResponseField>
    <ResponseField name="backupModel" type="string">Failover model. Null inherits.</ResponseField>
    <ResponseField name="reasoningEffort" type="string">`none`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. Null inherits.</ResponseField>
    <ResponseField name="sandboxSize" type="string">`small`, `medium` or `large`. Null inherits.</ResponseField>
    <ResponseField name="harness" type="string">Harness override. Null derives it from the model.</ResponseField>
    <ResponseField name="environment" type="string" required>`device` or `cloud`.</ResponseField>
    <ResponseField name="maxTurns" type="integer">Turn cap per run, 1 to 1,000. Null uses the workspace default, then no cap.</ResponseField>
    <ResponseField name="triggers" type="object" required>`wakeOnAssignment` and `wakeOnHook`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="config.permissions" type="object" required>
  <Expandable title="properties">
    <ResponseField name="tools" type="object" required>`allow`, `ask` and `deny` rule lists, and `defaultMode`.</ResponseField>
    <ResponseField name="capabilities" type="string[]" required>Any of `manage_agents`, `manage_projects`, `manage_runs`, `manage_secrets`.</ResponseField>
  </Expandable>
</ResponseField>

The agent has no access mode setting. Each run resolves it from the model and the provider key. The run shows it as `effectiveSettings.accessMode`: `credits`, `byok` or `subscription`.

An agent can change its own AGENT.md, `model`, `backupModel`, `reasoningEffort`, `sandboxSize`, `harness` and `maxTurns`. Any other change by an agent raises an approval. Changing `permissions` as a person needs a workspace admin.

### Config revisions

Each config write stores a revision. `GET /agents/{agentId}/revisions` lists them, newest first. A revision has `id`, `agentId`, `beforeConfig`, `afterConfig`, `changedKeys`, `changeDescription`, `source` (`patch` or `rollback`) and `createdAt`.

A rollback writes the revision's `afterConfig` back as a new revision with `source: "rollback"`. `agent history` and `agent revert` cover the same changes, plus skill and rule changes.

## CLI

| Command | Does |
| - | - |
| `pinework agent list` | List agents, newest first. Filter with `--status`, `--role` or `--q`. |
| `pinework agent get [<agent> …]` | Print one or more agents. Defaults to the caller. |
| `pinework agent create` | Create an agent. `--name` is required. `--role` defaults to `agent`. |
| `pinework agent update <agent>` | Change name, role, description, status, visibility, manager, folder, repo or AGENT.md. |
| `pinework agent config get [<agent>]` | Print the settings. |
| `pinework agent config set [<agent>]` | Set model, backup model, effort, max turns, harness, environment, sandbox size, mode or AGENT.md. |
| `pinework agent identity [<agent>]` | Print AGENT.md and the agent rules. The hash goes to stderr. |
| `pinework agent doctor [<agent>]` | Audit name, role, description and instructions. Changes nothing. |
| `pinework agent history [<agent>]` | List who changed which setting, newest first. `--kind` narrows. |
| `pinework agent revert <entryId>` | Undo one history entry. The revert is a new entry. |
| `pinework agent run [<agent>]` | Wake the agent for an on-demand run. Takes `--task-id` and `--prompt`. |
| `pinework agent delete <agent>` | Soft-delete the agent and unassign its open tasks. `agent restore` undoes it. |
| `pinework agent transfer-owner <agent>` | Give the agent to `--new-owner`. |

`agent run` also lists `--model`, `--effort` and `--env`. On main the request drops them, so the run uses the agent's settings. The `agent rule` verbs are on [Rule](/reference/rule).

```bash theme={null}
pinework agent create --name "Builder" --role "Builds features and opens pull requests" --model claude-sonnet-4-6 --environment cloud
pinework agent config set @builder --max-turns 200 --reasoning-effort high
pinework agent history @builder --kind agent.config
pinework agent update @builder --status terminated
```

## API

| Method | Path | Does |
| - | - | - |
| GET | `/api/v1/agents` | List agents. `ids=a,b` reads several at once. |
| POST | `/api/v1/agents` | Create an agent. Returns 201. |
| GET | `/api/v1/agents/{agentId}` | Read one agent. |
| PATCH | `/api/v1/agents/{agentId}` | Change identity, status, visibility, manager, folder or repo. |
| DELETE | `/api/v1/agents/{agentId}` | Soft-delete. Returns the unassigned tasks. |
| POST | `/api/v1/agents/{agentId}/restore` | Restore. Owner or workspace admin only. |
| GET | `/api/v1/agents/{agentId}/config` | Read settings and AGENT.md. |
| PUT | `/api/v1/agents/{agentId}/config` | Write settings, AGENT.md or both. |
| GET | `/api/v1/agents/{agentId}/revisions` | List config revisions. |
| GET | `/api/v1/agents/{agentId}/revisions/{revisionId}` | Read one revision. |
| POST | `/api/v1/agents/{agentId}/revisions/{revisionId}/rollback` | Roll config back to that revision. |
| GET | `/api/v1/agents/{agentId}/history` | List config history entries. |
| POST | `/api/v1/agents/{agentId}/history/{entryId}/revert` | Undo one history entry. |
| GET | `/api/v1/agents/{agentId}/identity` | Read AGENT.md, its hash and the agent rules. |
| PUT | `/api/v1/agents/{agentId}/identity/agent-md` | Replace AGENT.md. |
| GET | `/api/v1/agents/{agentId}/audit` | Run the agent doctor. |
| POST | `/api/v1/agents/{agentId}/clones` | Copy an agent under a new name. Returns 201. |
| POST | `/api/v1/agents/{agentId}/transfer-owner` | Set a new owner. Body `{newOwnerId}`. |
| GET | `/api/v1/agents/{agentId}/projects` | List projects the agent has a grant on. |
| POST | `/api/v1/agents/{agentId}/sessions/reset` | Make the next runs start a fresh harness session. |
| POST | `/api/v1/agents/{agentId}/runs` | Start a run. See [Run](/reference/run). |

Create, delete and clone by an agent raise an approval. So does an agent changing another agent. The route then returns 202 with `object: "platform_change"`, an `approvalId` and `status: "pending"`.

## Errors

| Code | HTTP | When | What to do |
| - | - | - | - |
| `config_write_forbidden` | 400 | A PATCH carried a settings key such as `model` or `maxTurns`. | Send it to `PUT /agents/{agentId}/config`. |
| `identity_write_forbidden` | 400 | An agent sent `identityMd` in a PATCH. | Use `agent update --agent-md`. |
| `invalid_status_transition` | 422 | The status move is not in the transitions table. | Pick an allowed target. |
| `reporting_cycle` | 400 | The new manager reports, directly or not, to this agent. | Pick another manager. |
| `handle_taken` | 409 | Another write took the same handle. | Save again. |
| `folder_requires_device_environment` | 422 | A cloud agent was given a default folder, or an agent with one was moved to the cloud. | Clear the folder, or keep the agent on a device. |
| `default_folder_forbidden`, `default_repo_forbidden` | 403 | You changed the folder or repo but are not the owner or a workspace admin. | Ask one of them. |
| `agent_self_only` | 403 | An agent read or wrote another agent's config, or reverted its history. | Act on your own agent. |
| `agent_config_human_only` | 403 | An agent reverted a change to a setting only a person may set. | Ask a person. |
| `agent_md_stale` | 409 | An agent saved AGENT.md without the current hash. | Re-apply the edit to `details.agentMd`, then send `details.agentMdHash`. |
| `config_revert_unsupported` | 422 | This kind of history entry cannot be reverted. | Make the change by hand. |
| `restore_forbidden` | 403 | You are not the owner or a workspace admin. | Ask one of them. |
| `not_deleted` | 409 | The agent is not deleted. | Nothing to restore. |
| `list_deleted_forbidden` | 403 | An agent listed deleted agents. | Ask a person. |
| `owner_transfer.forbidden` | 403 | You are not the owner or a workspace admin. | Ask one of them. |
| `owner_transfer.same_owner` | 409 | The agent already belongs to that user. | No change needed. |
| `owner_transfer.user_not_found` | 404 | The new owner is not a member. | Pick a member. |
| `platform_change_requires_run` | 403 | An agent outside a live run asked for a change that needs approval. | Ask from inside a run. |

A rollback returns 409 with an `error` string when the revision already matches the live config. Shared codes are in [API errors](/reference/api#errors).

## Limits

* `maxTurns` takes 1 to 1,000. Null falls back to the workspace's `defaultMaxTurns`, then to no cap.
* `GET /agents` returns 25 per page by default and 100 at most. `q` holds up to 100 characters.
* `ids` takes up to 100 refs.

<CardGroup cols={2}>
  <Card title="Agents" href="/concepts/agents">
    What an agent is and what wakes it.
  </Card>

  <Card title="Create an agent" href="/guides/create-an-agent">
    Add an agent and pick its model.
  </Card>

  <Card title="Run" href="/reference/run">
    What one wake of an agent produces.
  </Card>

  <Card title="Rule" href="/reference/rule">
    Agent rules and AGENT.md edits.
  </Card>
</CardGroup>


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