---
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 multiple patterns for multi-agent coordination, all built on pathways.

### Direct Agent Calls (Simplest)

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

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

### Conditional Routing (DAG Pathways)

Route a message to the best agent based on classification. Use `conditional`
nodes to branch, and `llm` nodes with tools to delegate work.

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

```python
from albusos import PathwayBuilder

workflow = (
    PathwayBuilder("router", pathway_id="router")
    .llm("classify", "Classify this request as 'research' or 'code': {{input.goal}}", model="fast",
         response_format="json")
    .conditional("route", "{{classify.output.approach}} == 'research'", "research", "code")
    .llm("research", "Research: {{input.goal}}", tools=["web.*", "memory.*"])
    .llm("code", "Write code: {{input.goal}}", tools=["code.*", "workspace.*"])
    .connect("input", "classify")
    .connect("classify", "route")
    .connect("route", "research")
    .connect("route", "code")
    .connect("research", "output")
    .connect("code", "output")
    .build()
)
```

Or use `agent.turn` inside an LLM node's tool loop for delegation:

```python
.llm("delegate", "Decide which agent to call and delegate:",
     tools=["agent.*"], max_tool_rounds=3)
```

### 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:

```python
from albusos import PathwayBuilder

pipeline = (
    PathwayBuilder("project", pathway_id="project")
    .stateful()
    .stage("intake", goal="Gather requirements", agent_id="system.planner",
           transitions=[("stage_result.success == True", "design")])
    .stage("design", goal="Design solution", agent_id="system.builder",
           transitions=[("true", "review")])
    .stage("review", goal="Review the design", agent_id="system.reviewer",
           transitions=[("approved == true", "done"), ("needs_revision == true", "design")])
    .connect("intake", "design")
    .connect("design", "review")
    .connect("review", "design")  # Cycles allowed in stateful mode
    .build()
)
```

## When to Use Each Pattern

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