## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Tutorial 2: Basic Agents

Learn how to register agents and execute tasks.

## Prerequisites

- Complete 01-getting-started.md
- VAPORA built: `cargo build`

## Learning Objectives

- Register agents in the agent registry
- Define agent capabilities and metadata
- Execute agent tasks
- Query agent status

## Step 1: Create Agent Registry

An `AgentRegistry` manages all registered agents.

    #![allow(unused)]
    fn main() {
    use vapora_agents::AgentRegistry;

    let registry = AgentRegistry::new(10); // capacity: 10 agents
    }

## Step 2: Define Agent Metadata

Each agent has a role, capabilities, and LLM provider.

    #![allow(unused)]
    fn main() {
    use vapora_agents::{AgentMetadata, AgentStatus};

    let agent = AgentMetadata::new(
        "developer".to_string(),           // role
        "Developer Alice".to_string(),     // name
        "claude".to_string(),              // provider
        "claude-opus-4-5".to_string(),    // model
        vec!["coding".to_string(), "testing".to_string()], // capabilities
    );
    }

## Step 3: Register Agent

Add the agent to the registry.

    #![allow(unused)]
    fn main() {
    let agent_id = registry.register_agent(agent)?;
    println!("Agent registered: {}", agent_id);
    }

## Step 4: Query Registry

List all agents or get specific agent.

    #![allow(unused)]
    fn main() {
    // Get all agents
    let all_agents = registry.list_all();

    // Get specific agent
    let agent = registry.get_agent(&agent_id)?;
    println!("Agent status: {:?}", agent.status);
    }

## Running the Example

    cargo run --example 01-simple-agent -p vapora-agents

## Expected Output

    === Simple Agent Registration Example ===

    Created agent registry with capacity 10
    Defined agent: "Developer A" (role: developer)
    Capabilities: ["coding", "testing"]

    Agent registered successfully
    Agent ID: <uuid>

    === Registered Agents ===
    Total: 1 agents
    - Developer A (Role: developer, Status: Ready, Capabilities: coding, testing)
    Retrieved agent: Developer A (Status: Ready)

## Concepts

### AgentRegistry

- Thread-safe registry for managing agents
- Capacity-limited (prevents resource exhaustion)
- In-memory storage

### AgentMetadata

- Unique ID (UUID)
- Role: developer, reviewer, architect, etc.
- Capabilities: coding, testing, documentation, etc.
- LLM Provider: claude, gpt-4, gemini, ollama
- Model: specific version (opus, sonnet, etc.)

### AgentStatus

- Ready: Available for task assignment
- Busy: Executing tasks
- Offline: Not available

## Common Patterns

### Register Multiple Agents

    #![allow(unused)]
    fn main() {
    let agents = vec![
        AgentMetadata::new(...),
        AgentMetadata::new(...),
    ];

    for agent in agents {
        registry.register_agent(agent)?;
    }
    }

### Filter by Capability

    #![allow(unused)]
    fn main() {
    let all_agents = registry.list_all();
    let developers = all_agents
        .iter()
        .filter(|a| a.role == "developer")
        .collect::<Vec<_>>();
    }

## Troubleshooting

Q: "Agent registry is full" A: Increase capacity: `AgentRegistry::new(20)`

Q: "Agent ID already registered" A: Use unique agent names or generate new IDs

## Next Steps

- Tutorial 3: LLM Routing
- Example: `crates/vapora-agents/examples/03-agent-selection.rs`

## Reference

- Source: `crates/vapora-agents/src/registry.rs`
- API Docs: `cargo doc --open -p vapora-agents`