velocia 0.2.0

<p align="center">
  <img src="image/logo.png" alt="velocia" width="600">
</p>

A Rust framework for building production-ready AI agents that communicate via the **A2A (Agent-to-Agent) protocol**. It wraps the [ADK-Rust](https://github.com/google/adk-rust) engine and exposes a declarative, YAML-driven API so you can go from config to a running HTTP agent server with minimal boilerplate.

## Purpose

`velocia` solves the gap between raw LLM SDKs and deployable multi-agent systems. You define an agent in a YAML file — its model, instructions, skills, tools, and auth — and the framework handles:

- **A2A protocol server** — JSON-RPC over SSE, `AgentCard` discovery at `/.well-known/agent.json`, streaming task/artifact events
- **Multi-agent orchestration** — agents can call other agents as remote tools via their A2A address
- **Tool loading** — MCP servers, custom Rust functions, or remote agent addresses declared in config
- **Session persistence** — optional AWS DynamoDB backend for conversation history
- **Observability** — optional OpenTelemetry traces to Phoenix or Arize
- **Authentication** — JWT middleware with configurable security schemes
- **Container-first deployment** — each agent is a self-contained Docker image; compose files wire up multi-agent systems

## Architecture

```
agent_config.yaml
       │
       ▼
 AgentFactory::from_config()
       │
       ├─► AgentCard  (served at /.well-known/agent.json)
       │
       └─► AgentExecutor (ADK-Rust engine)
                │
                ├─► Tools (MCP / function / remote agent)
                └─► Model (Gemini, OpenAI, Anthropic, …)
                         │
                    Axum HTTP server
                    POST /  →  SSE stream (A2A)
```

## Quick Start

**1. Define your agent** in `agent_config.yaml`:

```yaml
name: my_agent
description: Does something useful
url: http://my-agent:8080
version: 1.0.0

agent:
  type: adk
  model:
    name: google_genai:gemini-2.5-flash
    hyperparameters:
      temperature: 0.7

instruction: |
  You are a helpful assistant. Answer concisely.

capabilities:
  streaming: true

skills:
  - id: answer_questions
    name: Answer Questions
    description: Answers user questions
    tags: [qa]
```

**2. Create the binary** (`main.rs`):

```rust
use velocia::AgentFactory;

#[tokio::main]
async fn main() {
    dotenvy::dotenv().ok();
    let factory = AgentFactory::from_config("agent_config.yaml").unwrap();
    factory.run_server(8080).await.unwrap();
}
```

**3. Set your API key** (`.env`):

```env
GOOGLE_API_KEY=your_key_here
```

**4. Run it**:

```bash
cargo run --example hello_world_agent
# → http://localhost:8080
# → http://localhost:8080/.well-known/agent.json
```

## Cargo Features

| Feature | Description |
|---|---|
| `adk` (default) | ADK-Rust engine — required for agent execution |
| `dynamodb` | DynamoDB-backed session persistence |
| `observability` | OpenTelemetry traces (Phoenix / Arize) |
| `all` | All of the above |

Enable in `Cargo.toml`:

```toml
velocia = { version = "0.1", features = ["all"] }
```

## Examples

### Hello World Agent

A minimal single agent that greets users and can analyse documents (PDF, images, URLs).

```bash
cd examples/hello_world_agent
docker compose up
```

### Travel Planning System

A multi-agent system with three cooperating agents:

| Agent | Port | Role |
|---|---|---|
| `flight-booking-assistant` | 8081 | Searches and books flights |
| `hotel-booking-assistant` | 8082 | Searches and books hotels |
| `travel-coordinator` | 8089 | Orchestrates the other two |

The coordinator discovers the sub-agents via their A2A `AgentCard` and delegates tasks to them automatically. An [A2A Inspector](https://github.com/a2aproject/a2a-inspector) is also included on port 6007 for debugging.

```bash
cd examples/travel_planning_system
cp .env.example .env   # fill in API keys
docker compose up
```

## Project Structure

```
src/
├── agents/        # AgentFactory, AgentExecutor, ADK builder
├── a2a/           # A2A protocol types (AgentCard, Task, Message, SSE events)
├── config/        # YAML schema (agent, model, tools, auth)
├── tools/         # Tool factory: MCP, function, remote-agent loaders
├── repositories/  # DynamoDB session repository
├── observability/ # OpenTelemetry / tracing setup
└── lib.rs         # Public API surface

examples/
├── hello_world_agent/          # Single-agent example
└── travel_planning_system/     # Multi-agent orchestration example
```

## Requirements

- Rust 1.78+
- A supported LLM API key (Google Gemini by default; OpenAI and Anthropic available via ADK-Rust features)
- Docker + Docker Compose (for containerised examples)
- AWS credentials (only if using the `dynamodb` feature)

## License

Apache-2.0