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

# Agent-to-Agent Delegation

> Have one Programmable Agent spawn and coordinate other DinoAI agents so complex analytics workflows split into focused, composable sub-agents you can version.

Programmable Agents can spawn and coordinate other agents, enabling complex multi-agent workflows where each agent has a focused responsibility.

***

### How Delegation Works

An agent with `invoke_agent` in its tool allowlist can spawn child agents. Each child runs in its own pod and — if a Slack channel is configured — posts to the same thread as the parent.

To allow delegation, two things must be configured in the parent agent's YAML:

1. `invoke_agent` must be included in `tools.list`
2. The child agent name must be listed under `agents_squad`

```yaml theme={"system"}
tools:
  mode: allowlist
  list:
    - invoke_agent

agents_squad:
  - test-maintainer
```

***

### Callback / Resume Pattern

For workflows where the parent needs the child's result before continuing, pass `callback_session_id` to `invoke_agent`. The parent pod idles until the child calls `notify_parent_session`, then wakes up with the child's output as its next input.

The parent does not idle forever: it stays alive up to its inactivity timeout (24 hours) and hard lifetime limit (48 hours). If the child takes longer than that, or fails to call back, the parent shuts down.

```mermaid theme={"system"}
sequenceDiagram
    participant A as PR Reviewer (Session A)
    participant B as Test Maintainer pod
    participant S as Slack

    A->>B: invoke_agent("test-maintainer",<br/>callback_session_id=A)
    note over A: pod idles — awaiting callback
    B->>S: "Writing tests for stg_orders..."
    B->>B: Commit + run dbt test
    B->>S: "Tests passing ✓"
    B->>A: notify_parent_session("Tests complete. All passing.")
    note over A: wakes — receives child output<br/>as next user turn
    A-->>A: "All checks passed. PR approved ✓"

```

***

### Limiting Delegation Depth

Depth is implicitly limited by whether `invoke_agent` appears in a child agent's allowlist. If the `test-maintainer` above does not include `invoke_agent` in its tools, it cannot delegate further — the chain stops there.

This is the recommended approach: only give `invoke_agent` to orchestrator agents, not to leaf agents.

***

### `invoke_agent` vs `run_subagent`

Both let an agent hand off work, but they are different mechanisms:

* **`invoke_agent`** spawns a **named agent** (defined under `.dinoai/agents/`) in its **own pod**, running asynchronously with its own tools and Slack thread. Use it for durable, specialized agents and for the callback pattern above.
* **`run_subagent`** runs a **lightweight, read-only research task in the same pod**, synchronously, and returns its findings inline. It has no YAML definition, no Slack thread, and no callback. Use it for quick lookups where spawning a full agent is overkill.

***

### Related

* [YAML Configuration](/products/dino-ai/programmable-agents/yaml-configuration) — `agents_squad` and `tools` fields
* [Tools Reference](/products/dino-ai/programmable-agents/tools-reference) — `invoke_agent`, `notify_parent_session`, `run_subagent`
* [Examples](/products/dino-ai/programmable-agents/index) — See tutorials on how to get started deploying agents


## Related topics

- [Creating Agents in the App](/products/dino-ai/programmable-agents/creating-agents-in-the-app.md)
- [Agent Sessions](/products/dino-ai/mcp-server/agent-sessions.md)
- [Programmable Agents](/products/dino-ai/programmable-agents/index.md)
- [YAML Configuration](/products/dino-ai/programmable-agents/yaml-configuration.md)
- [Triggering from the API](/products/dino-ai/programmable-agents/api-reference.md)