---
title: "Implement Multi-Agent Delegation"
url: "https://docs.caracal.run/guides/delegation/"
markdown_url: "https://docs.caracal.run/markdown/guides/delegation.md"
description: "Spawn child agents, attach typed constraints, inspect graph impact, and revoke safely."
page_type: "page"
concepts: []
requires: []
---

# Implement Multi-Agent Delegation

Canonical URL: https://docs.caracal.run/guides/delegation/
Markdown URL: https://docs.caracal.run/markdown/guides/delegation.md
Description: Spawn child agents, attach typed constraints, inspect graph impact, and revoke safely.
Page type: page
Concepts: none
Requires: none

---

Use delegation when one agent needs to hand a narrower slice of authority to another agent. The SDK creates the edge and carries the context; the web console shows the graph and impact.

`spawn()` always creates the child under the **same application** as the parent — `spawn()` never moves a child into a different application. Use a narrowing grant only when the child should hold *less* than the parent. To hand authority across applications, use `delegate()` against a peer session that already exists under that other application.

## Implementation flow

```mermaid
flowchart LR
  Parent["Parent agent session"] --> Spawn["Spawn child with narrowing grant"]
  Spawn --> Edge["Bounded delegation edge"]
  Edge --> Child["Run child with delegated context"]
  Child --> Exchange["Exchange for resource mandate"]
  Exchange --> Audit["Inspect audit and graph"]
```

## TypeScript example

```ts
import { Caracal, Grant } from "@caracalai/sdk";

const caracal = new Caracal();

await caracal.spawn(async () => {
  await caracal.spawn(async () => {
    const headers = await caracal.headersAsync();
    await fetch("https://api.example.com/tickets", { headers });
  }, {
    grant: Grant.narrow(["tickets:read"], {
      resourceId: "https://api.example.com/tickets",
      constraints: { maxHops: 1, budget: 5 },
      ttlSeconds: 600,
    }),
  });
});
```

## Review the graph

1. Open `caracal web`.
2. Select **Delegation**.
3. Inspect active edges, inbound edges, outbound edges, and traversal.
4. Use impact before revoking an edge.
5. Check **Audit** for the delegated exchange and resource decision.

## Safe constraints

| Constraint | Good default |
| --- | --- |
| Scopes | Small subset of parent authority. |
| TTL | Minutes, not days. |
| Hop count | `1` unless a deeper graph is intentional. |
| Budget | Explicit request or work limit. |
| Resource | Single resource whenever possible. |

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `Delegate requires an active agent session` | Call delegation inside `spawn()` or a bound Caracal context. |
| Resource denies delegated request | Confirm policy accepts the edge constraints and required scopes. |
| Chain validation fails | Confirm the expected application appears in the delegation path. |
| Revocation did not affect child | Confirm cascade revocation and resource-server revocation consumers. |

Related pages: [Agent Delegation](/concepts/delegation/) and [Delegation Constraints](/concepts/constraint/).