Blueprint Agents

A Python framework for building production-ready AI agent microservices with event-driven architecture.

Blueprint Agents gives you a component-based toolkit for building intelligent microservices that process events, call LLMs, expose REST APIs, and run scheduled tasks -- all wired together with a fluent builder API and backed by production-grade observability.

---

Key Features

• Component Architecture -- Five composable base classes (EventHandlerBase, ServiceBase, RestApiBase, AgentRuntime, SchedulerBase) assembled via a fluent AppBuilder
• Event-Driven Processing -- CloudEvents v1.0 with chain-of-responsibility handlers, Dapr and NATS pub/sub support
• LLM Integration -- AI agents powered by Pydantic AI with structured outputs, tool calling, and multi-model support (OpenAI, vLLM)
• Built-in Observability -- OpenTelemetry tracing, metrics, and structured logging out of the box
• CLI Scaffolding -- Generate complete project structures and individual components with the asbs CLI
• Deployment Ready -- Docker, Kubernetes with Helm charts, health checks, and CI/CD patterns included

---

Quick Start

# Install the framework
pip install avs-blueprint-agents

# Scaffold a new project
asbs setup my-agent

# Start developing
cd my-agent
pip install -e .
asbs dev

Your service is now running at http://localhost:8000 with interactive API docs at /docs.

---

Installation

Stable Release (PyPI)

pip install avs-blueprint-agents

Or with uv:

uv add avs-blueprint-agents

Alpha Release (TestPyPI)

To install the latest alpha version for testing, add the TestPyPI index to your pyproject.toml:

[[tool.uv.index]]
name = "test-pypi"
url = "https://test.pypi.org/simple/"
priority = "supplemental"

Then install:

uv add avs-blueprint-agents

Or with pip:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ avs-blueprint-agents

From Source

git clone https://github.com/2SpeakAI/blueprint-agents.git
cd blueprint-agents
pip install -e ".[dev]"

---

How It Works

Blueprint Agents uses five composable component types, wired together with the AppBuilder:

from blueprint.agents import AppBuilder, AgentBuilder, Config

from src.handlers.order_handler import OrderHandler
from src.services.order_service import OrderService
from src.api.routes import OrderApi

config = Config(settings_files=["settings.toml", "secrets.toml"])

app = (
    AppBuilder(config)
    .with_handler(OrderHandler)
    .with_service(OrderService)
    .with_rest_api(OrderApi())
    .with_cache()
    .build()
)

The Five Components

Component	Base Class	Purpose
Event Handler	EventHandlerBase	Process CloudEvents via chain-of-responsibility with priority ordering
Service	ServiceBase	Encapsulate business logic with full registry access
REST API	RestApiBase	Define HTTP endpoints with @get(), @post(), @put(), @delete(), @patch() decorators
Agent	AgentRuntime	Run LLM agents with structured outputs, tool calling, and prompt management
Scheduler	SchedulerBase	Execute cron-based background tasks with auto-registered trigger endpoints

Component Lifecycle

All components follow a consistent lifecycle managed by the framework:

__init__()     -->  Register with component registry
on_startup()   -->  Resolve dependencies, connect to external services
[running]      -->  Process events, handle requests, run tasks
on_shutdown()  -->  Clean up resources, close connections

---

Examples

Explore complete, runnable examples in the examples/ directory:

Example	Description	Components Used
inventory_api	Product inventory CRUD REST API	RestApiBase, ServiceBase, Cache
order_event_pipeline	E-commerce order processing with Dapr pub/sub	EventHandlerBase, ServiceBase, Dapr
document_summarizer	LLM-powered document summarization with structured output	AgentRuntime, AgentBuilder, Tools
webhook_relay	Webhook ingestion and normalization pipeline with NATS	EventHandlerBase, NATS, Cache
health_monitor	System health monitoring with scheduled checks	SchedulerBase, ServiceBase, Cache

---

Configuration

Blueprint Agents uses Dynaconf for hierarchical configuration via TOML files:

settings.toml (checked into version control):

[default]
app_name = "my-agent"
app_port = 8000
event_bus = "dapr"          # "dapr", "nats", or "sessions"
log_level = "INFO"

[default.runtimes.my_agent]
model_provider = "openai"
model_name = "gpt-4o-mini"
model_max_tokens = 1000
model_temperature = 0.3

[default.cache]
cache_dir = ".cache/my-agent"
default_ttl = 3600

secrets.toml (never commit this file):

[default.runtimes.my_agent]
model_api_key = "sk-your-api-key"

For the sessions transport (consumes SSE jobs from service-sessions):

[default]
event_bus = "sessions"

[default.sessions_service]
base_url = "http://sessions:8000"
agent_id = "my-agent"
agent_type = "analyser"
capabilities = ["analyse_documents"]
api_key = "@format {env[SESSIONS_API_KEY]}"
# Optional per-agent HS256 bearer token. When set, sent as `Authorization: Bearer <token>`
# alongside `X-Api-Key` on the gated sessions routes (register, SSE stream, session-key fetch).
# To opt out, OMIT this line entirely (ungated sessions, X-Api-Key only). Do NOT keep the line
# with SESSIONS_AGENT_TOKEN undefined — Dynaconf fails config load on an unresolved `@format`.
agent_token = "@format {env[SESSIONS_AGENT_TOKEN]}"
max_concurrent_jobs = 5
job_timeout_seconds = 300

The bearer is only sent when agent_token is configured, so agents keep working against ungated sessions and can be rolled out before the gate is flipped. The token is an offline-minted HS256 JWT whose sub equals the agent's agent_id and whose caps claim is its capability ceiling (see service-sessions#198/#326). Never commit the token value — inject it via the SESSIONS_AGENT_TOKEN environment variable (e.g. YOUR_AGENT_TOKEN).

Opting out cleanly: because the value above is a Dynaconf @format interpolation, keeping the agent_token line while SESSIONS_AGENT_TOKEN is undefined raises DynaconfFormatError at config load — the agent won't start. To run against ungated sessions, either omit the line entirely or export an empty SESSIONS_AGENT_TOKEN= (both yield X-Api-Key-only behaviour).

The token is read once at startup (like api_key) and is not hot-reloaded. If the JWT carries an exp, mint it long-lived enough to outlast the agent process and restart the agent to roll a renewed token — an expired bearer makes the gated routes return 401/403, and the SSE consumer will reconnect-and-retry with the same stale token until it is restarted.

No SessionsBus, SessionsApiClient, or SessionKeyProvider references in service main.py — AppBuilder.build() wires them automatically.

See the Configuration Reference for all available settings.

---

CLI Reference

The asbs CLI scaffolds projects and components:

asbs setup <project-name>                         # Create a new project
asbs create handler <name> [--event-type <type>]  # Add an event handler
asbs create service <name>                        # Add a business service
asbs create api <name>                            # Add a REST API
asbs create agent <name>                          # Add an AI agent
asbs create scheduler <name> [--cron <expr>]      # Add a scheduler
asbs validate                                     # Validate project structure
asbs dev [--port <port>]                          # Run development server

See the full CLI Reference.

---

Deployment

Blueprint Agents services deploy as standard Python containers:

• Docker -- Multi-stage Dockerfile included with scaffolded projects
• Kubernetes -- Helm charts with Dapr sidecar injection, health probes, and ConfigMap/Secret management
• CI/CD -- GitHub Actions workflows for linting, testing, and publishing

See the Deployment Guide for detailed instructions.

---

Documentation

Getting Started

• Getting Started Guide -- Installation, first project, and walkthrough

Core Concepts

• Architecture -- Component model, registry, and lifecycle
• Event Processing -- CloudEvents, handler chain, Dapr/NATS
• Configuration -- Settings, secrets, and environment variables
• Caching -- Persistent disk cache with TTL and namespaces
• Observability -- OpenTelemetry tracing, metrics, and logging

Component Guides

• Event Handlers
• Services
• REST APIs
• Agents
• Schedulers

Operations

• CLI Reference
• Testing Guide
• Deployment Guide
• Troubleshooting

Reference

• API Reference
• Configuration Keys
• Data Models

---

Requirements

• Python 3.13+
• Docker (optional, for containerized deployment)
• Dapr CLI (optional, for Dapr pub/sub event processing)
• NATS Server (optional, for NATS event processing)
• API keys for AI providers (optional, only for LLM agent features)

---

Contributing

We welcome contributions! See CONTRIBUTE.md for guidelines on:

• Setting up the development environment
• Running tests and linting
• Submitting pull requests

---

License

This project is licensed under the MIT License. See LICENSE for details.