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
• 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.

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.

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.

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

Step 4: Query Registry

List all agents or get specific agent.

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

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

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

Filter by Capability

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