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

# Agent domain API

> Protocol contracts for explicit agent delegation routes and durable agent work attribution.

Pioneer exposes agent work as typed protocol data. An agent execution has an identity, an actor reference, and an authorization context. When it delegates, the gateway creates an explicit route instead of copying the initiating principal's full access.

See [Agent domain and delegation](https://docs.getpioneer.dev/architecture/agent-domain.md) for the data model and admission rules.

## Route methods

| Method | Params | Result | Purpose |
| - | - | - | - |
| `agent/route/create` | `AgentDelegationRouteCreateParams` | `AgentDelegationRouteProjection` | Create a bounded route from an agent execution to a destination thread. |
| `agent/route/list` | `AgentDelegationRouteListParams` | `AgentDelegationRouteListResponse` | List routes from one source execution with a cursor. |
| `agent/route/revoke` | `AgentDelegationRouteRevokeParams` | `AgentDelegationRouteProjection` | Revoke a route with generation and idempotency checks. |

## Route projection

`AgentDelegationRouteProjection` includes:

| Field | Meaning |
| - | - |
| `kind` | `execution_bound` or `identity_bound`. |
| `status` | `prepared`, `active`, `expired`, or `revoked`. |
| `allowed_actions` | `send_message`, `start_agent`, `create_task`, `schedule_task`, `review_task_result`, or `deliver_result`. |
| `disclosure` | Independent flags for text, artifacts, context, user input, and result return. |
| `generation` | Version used for revocation and admission checks. |
| `source_policy_generation` | Policy revision captured at the source. |
| `destination_policy_generation` | Policy revision captured at the destination. |
| `hop_count`, `max_hops` | Bounds for nested delegation. |
| `grant_fingerprint` | Opaque receipt for the route grant. |
| `expires_at` | Route expiry, when one is set. |
| `return_route_id` | Optional route for a result to travel back. |

The projection also carries source and destination execution, capsule, thread, workspace, and gateway ids. Destination identity and execution profile are optional constraints.

## Disclosure policy

Disclosure classes are explicit:

```json theme={null}
{
  "text": true,
  "artifacts": true,
  "context": false,
  "userInput": true,
  "resultReturn": "summary_only"
}
```

`resultReturn` is `none`, `summary_only`, or `full_result`. A route that allows authored text does not automatically allow a task result. Artifact disclosure refers to already authorized artifact handles, not arbitrary paths or raw files.

## Validation

The gateway rejects routes with no actions, duplicate actions, invalid generations, invalid expiry, missing disclosure, cross-workspace or cross-gateway destinations, invalid hop boundaries, or incompatible result-return policy. The graph validator also rejects cycles and excessive edge counts.

Route creation is idempotent when the caller supplies an idempotency key. Revoke uses the expected generation so a stale caller cannot overwrite a newer route state. A route is admitted only when it is active, unexpired, and compatible with current authorization and policy generations.

## Agent attribution

Agent-authored turns, task runs, and review events carry durable actor references and an immutable presentation snapshot. The snapshot contains the identity id, execution id, source and revision, display name, nickname, avatar revision, and role presentation. Clients should render that snapshot instead of replacing historical authors with the current agent profile.

The task and turn APIs expose these fields alongside normal lifecycle state. Combine them with `task/tree`, `task/events`, `thread/timeline/page`, and `turn/work/page` when rendering a work graph.

## Generated schemas

* `/schemas/agent_delegation_route_projection.json`
* `/schemas/agent_delegation_route_create_params.json`
* `/schemas/agent_delegation_route_list_params.json`
* `/schemas/agent_delegation_route_list_response.json`
* `/schemas/agent_delegation_route_revoke_params.json`
* `/schemas/agent_presentation_snapshot.json`

The create and revoke methods return the route projection directly, so they do not have separate response schema files. Action normalization uses `NormalizedAgentAction`; there is no standalone `agent_action.json` schema in the current generator.


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