Vapora/docs/tutorials/02-basic-agents.md

# Tutorial 2: Basic Agents

Learn how to register agents and execute tasks.

## Prerequisites

- Complete [01-getting-started.md](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.

```rust
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.

```rust
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.

```rust
let agent_id = registry.register_agent(agent)?;
println!("Agent registered: {}", agent_id);
```

## Step 4: Query Registry

List all agents or get specific agent.

```rust
// 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

```bash
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

```rust
let agents = vec![
    AgentMetadata::new(...),
    AgentMetadata::new(...),
];

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

### Filter by Capability

```rust
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](03-llm-routing.md)
- 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`