150 lines
3.1 KiB
Markdown
150 lines
3.1 KiB
Markdown
# 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`
|