velocia 0.2.0

A Rust framework for building production-ready AI agents that communicate via the A2A (Agent-to-Agent) protocol. It wraps the 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:

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):

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):

GOOGLE_API_KEY=your_key_here

4. Run it:

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

Cargo Features

Enable in Cargo.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).

cd examples/hello_world_agent
docker compose up

Travel Planning System

A multi-agent system with three cooperating agents:

The coordinator discovers the sub-agents via their A2A AgentCard and delegates tasks to them automatically. An A2A Inspector is also included on port 6007 for debugging.

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