---
name: agent
id: agent
version: "1.0"
description: Agent lifecycle and orchestration tools
tags:
  - orchestration
  - agent
  - multi-agent
triggers: []
---

# Agent Orchestration

Tools for agent lifecycle management and multi-agent coordination.

## Tools

- `agent.turn` -- Execute a turn with a specific agent
- `agent.list` -- List available agents and their capabilities

## Orchestration Patterns

AlbusOS supports two patterns for multi-agent coordination, both built on pathways.

### Handoff Pattern (DAG pathways)

Route a message to the best agent based on capabilities. The host agent's turn
completes before the target agent starts -- no nested call stacks.

Use this when you need **one-shot delegation**: classify a request, pick the
right specialist, and return the result.

```yaml
# In a pathway definition
route:
  type: handoff
  candidates:
    - agent_id: system.researcher
      description: "Information gathering"
      when: "{{classify.output.approach}} == 'research'"
    - agent_id: system.coder
      description: "Code tasks"
      when: "{{classify.output.approach}} == 'code'"
  fallback: direct_answer
  message: "{{input.message}}"
```

Or programmatically:

```
pathway.add_node(
    node_id="route",
    node_type="handoff",
    candidates=[
        {"agent_id": "system.researcher", "description": "Research tasks", "when": "..."},
        {"agent_id": "system.coder", "description": "Code tasks", "when": "..."},
    ],
    fallback="direct_answer",
    message="{{input.message}}"
)
```

### Stage Pattern (Stateful pathways)

Assign agents to stages in a multi-turn pathway. Each stage has a goal, an
agent, and conditional transitions to the next stage. The pathway persists
state between turns, enabling long-running processes.

Use this when you need **multi-step orchestration**: intake -> design -> review -> done.

```yaml
# In a stateful pathway definition
intake:
  type: stage
  agent_id: system.planner
  goal: "Gather requirements from the user"
  transitions:
    - ["stage_result.success == True", "design"]
    - ["true", "intake"]  # loop until success

design:
  type: stage
  agent_id: system.builder
  goal: "Design a solution based on: {{intake.output}}"
  transitions:
    - ["true", "review"]
```

Or programmatically:

```
pathway.new(name="Project Pipeline", mode="stateful")
pathway.add_node(node_id="intake", node_type="stage", agent_id="system.planner", goal="Gather requirements")
pathway.add_node(node_id="design", node_type="stage", agent_id="system.builder", goal="Design solution")
```

### Direct Agent Calls

For simple cases, use `agent.turn` directly without building a pathway:

```
agent.turn(agent_id="system.researcher", message="Find recent papers on transformers")
```

## When to Use Each Pattern

| Pattern | Use When |
| --- | --- |
| `agent.turn` | Simple one-off delegation to a known agent |
| Handoff (DAG) | Routing based on dynamic conditions or classification |
| Stage (Stateful) | Multi-step processes with transitions and state |
