agenkit

Agenkit

Build production-ready AI agent systems.

Agenkit is a lightweight, cross-language toolkit for building distributed AI agents that scale from prototype to production without rewriting your code.

Why Agenkit?

The Problem

Building production AI agent systems is hard:

• Reliability: LLMs fail unpredictably - you need circuit breakers, retries, and timeouts
• Scale: Prototypes work locally but break in production when you need distributed deployment
• Observability: Understanding what went wrong requires distributed tracing across services
• Language Lock-in: Python is great for prototyping, but you need Go/Rust for performance
• Integration: Every agent framework has its own incompatible abstractions

The Solution

Agenkit provides the production infrastructure you need:

Prototype → Production
┌─────────────────────────────────────────────┐
│  Your Agents (Python for development)      │
└──────────────┬──────────────────────────────┘
               │
               │ Same Interface
               ↓
┌─────────────────────────────────────────────┐
│  Agenkit Toolkit                            │
│  • Automatic retries & circuit breakers    │
│  • Distributed tracing & metrics           │
│  • Cross-language support (Python ↔ Go)    │
│  • Multiple transports (HTTP/gRPC/WS)      │
└─────────────────────────────────────────────┘

Key Insight: Write your agents once in Python. Deploy them in Go for 18x better performance. Same interface, zero rewrites.

Quick Start

30 Second Example

Create a simple agent:

from agenkit import Agent, Message

class MyAgent(Agent):
    @property
    def name(self) -> str:
        return "my-agent"

    async def process(self, message: Message) -> Message:
        return Message(
            role="agent",
            content=f"Processed: {message.content}"
        )

# Use it
agent = MyAgent()
response = await agent.process(Message(role="user", content="Hello!"))

Add Production Features in 3 Lines

from agenkit.middleware import RetryDecorator, CircuitBreakerDecorator

# Wrap with resilience (v0.50.0)
production_agent = RetryDecorator(
    CircuitBreakerDecorator(agent),
    max_attempts=3
)

# Now handles failures automatically
response = await production_agent.process(message)

Deploy Anywhere

# Run locally
python my_agent.py

# Deploy with Docker
docker-compose up

# Scale with Kubernetes
kubectl apply -f deploy/kubernetes/

Core Features

🎯 Simple, Minimal Interface

class Agent:
    name: str                          # Unique identifier
    async def process(msg) -> Message  # Process messages

That's it. Everything else is optional.

🔄 Production Middleware (Add What You Need)

# Start simple
agent = MyAgent()

# Add retry logic
agent = RetryDecorator(agent, max_attempts=3)

# Add circuit breaker
agent = CircuitBreakerDecorator(agent, failure_threshold=5)

# Add timeouts (v0.50.0: timeout_ms for clarity)
agent = TimeoutDecorator(agent, timeout_ms=30000)

# Stack as many as you need

Every middleware is <100 lines. Easy to understand, modify, or replace.

🌐 Cross-Language Support

Write once. Deploy anywhere. Six languages at 100% parity:

# Python - Prototype quickly with ML ecosystem
class MyAgent(Agent):
    async def process(self, message):
        return process_with_python_libs(message)

// TypeScript - Full-stack with browser support
class MyAgent implements Agent {
    async process(message: Message): Promise<Message> {
        return processWithTypeScriptLibs(message);
    }
}

// Go - Production scale (18x faster than Python)
type MyAgent struct{}

func (a *MyAgent) Process(ctx context.Context, msg *Message) (*Message, error) {
    return processWithGoLibs(msg)
}

// C++ - Maximum performance with zero-overhead abstractions
class MyAgent : public Agent {
public:
    Message process(const Message& msg) override {
        return process_with_cpp_libs(msg);
    }
};

// Rust - Memory safety + performance (20x faster than Python)
struct MyAgent;

impl Agent for MyAgent {
    async fn process(&self, message: Message) -> Result<Message, AgentError> {
        process_with_rust_libs(message).await
    }
}

// Zig - Systems programming with safety (22x faster than Python)
const MyAgent = struct {
    pub fn process(self: *MyAgent, message: Message) !Message {
        return processWithZigLibs(message);
    }
};

Same interface across all 6 languages. Choose the right tool for each service.

📊 Full Observability

from agenkit.observability import TracingMiddleware, init_tracing

# Enable tracing
init_tracing("my-service")

# Wrap agent
traced_agent = TracingMiddleware(agent)

# Every operation now traced in Jaeger

View traces: http://localhost:16686

🔍 Agent Introspection

# Inspect agent state during debugging or production
result = agent.introspect()

print(f"Agent: {result.agent_name}")
print(f"Capabilities: {result.capabilities}")
print(f"Internal state: {result.internal_state}")
print(f"Memory: {result.memory_state}")

# Use for monitoring
def check_agent_health(agent):
    result = agent.introspect()
    return result.internal_state.get("error_count", 0) < 10

# Use for testing
def test_agent_state():
    result1 = agent.introspect()
    await agent.process(message)
    result2 = agent.introspect()
    assert result2.internal_state["msg_count"] > result1.internal_state["msg_count"]

Introspection ≠ Reflection:

• Introspection (this feature): Examines current state ("What do I know?")
• Reflection (pattern): Analyzes past performance ("How did I do?")

🚀 Multiple Transports

from agenkit.adapters.python import HTTPServer, GRPCServer, WebSocketServer

# Same agent, different transports
HTTPServer(agent, port=8080).start()       # REST API
GRPCServer(agent, port=50051).start()      # High performance
WebSocketServer(agent, port=8765).start()  # Bidirectional streaming

Choose the right protocol for each use case.

When Should You Use Agenkit?

✅ Perfect For:

• Building production AI agent systems that need to scale
• Teams that prototype in Python but deploy in Go
• Systems that need resilience (retries, circuit breakers, timeouts)
• Distributed agent systems that need observability
• Integrating multiple AI agent frameworks

❌ Not For:

• Simple one-off scripts (too much overhead)
• Embedded systems (requires async runtime)
• Real-time systems (<1ms latency requirements)

Installation

Core Installation

# Python
pip install agenkit

# Go
go get github.com/agenkit/agenkit-go

# TypeScript/Node.js
npm install @agenkit/core

# C++
# Clone and build (CMake required)
git clone https://github.com/agenkit/agenkit.git
cd agenkit/agenkit-cpp && mkdir build && cd build && cmake .. && make

# Rust
cargo add agenkit

# Zig
# Clone and build (Zig 0.12+ required)
git clone https://github.com/agenkit/agenkit.git
cd agenkit/agenkit-zig && zig build

Python: Install with Specific LLM Providers

# Install only what you need
pip install agenkit[openai]          # OpenAI (GPT-4, GPT-3.5)
pip install agenkit[anthropic]       # Anthropic (Claude 3.5)
pip install agenkit[aws]             # AWS Bedrock
pip install agenkit[google]          # Google Gemini
pip install agenkit[ollama]          # Ollama (local models)

# Multiple providers
pip install agenkit[openai,anthropic]

# All providers
pip install agenkit[all-providers]

# With Redis memory backend
pip install agenkit[redis]

# Everything (for development)
pip install agenkit[all]

See INSTALLATION.md for complete installation guide.

What's Included?

Core Framework

• Minimal interfaces - Agent, Message, Tool (50 lines total)
• Orchestration patterns - Sequential, Parallel, Router, Fallback
• Type safety - Full type hints (Python), compile-time checks (Go)

Production Middleware (Optional)

• Circuit Breaker - Prevent cascading failures
• Retry - Exponential backoff with jitter
• Timeout - Request deadline enforcement
• Rate Limiter - Token bucket algorithm
• Caching - LRU cache with TTL
• Batching - Request aggregation

Transport Layer (Optional)

• HTTP - REST APIs (HTTP/1.1, HTTP/2, HTTP/3)
• gRPC - High-performance binary protocol
• WebSocket - Bidirectional streaming

Observability (Optional)

• Distributed Tracing - OpenTelemetry integration
• Metrics - Prometheus endpoints
• Structured Logging - JSON logs with trace correlation

Autonomous Agent Features (Optional)

• Memory Management - Context retention with compression strategies
• Budget Tracking - Token counting and cost optimization
• Checkpointing - State persistence and recovery
• Safety - Prompt injection detection, input/output validation
• Evaluation - Quality metrics and benchmarking

Performance

Transport Overhead: <1% of total time in realistic LLM workloads

Language Performance:

• Go HTTP: 18.5x faster than Python (0.055ms vs 1.02ms)
• Middleware overhead: <0.01% of request time

Scale:

• Kubernetes autoscaling: 3-10 replicas based on load
• Message size scaling: 10,000x size = 190x latency (linear)

See benchmarks/BASELINES.md for detailed performance data.

Production Ready

1500+ Tests Passing

• 47 cross-language integration tests (Python ↔ Go ↔ C++)
• 53 chaos engineering tests (network failures, crashes)
• 37 property-based tests (invariant validation)
• 1,360+ unit and integration tests across 5 languages

Security

• Input validation
• Prompt injection detection
• RBAC and audit logging
• Non-root containers
• Dropped capabilities

Observability

• Jaeger distributed tracing
• Prometheus metrics
• Structured JSON logging
• Health check endpoints

Deployment

• Docker images
• Kubernetes manifests with HPA
• Horizontal pod autoscaling (3-10 replicas)
• Zero-downtime rolling updates

Architecture

┌─────────────────────────────────────────┐
│   Your Application (Agents + Logic)    │
└──────────────┬──────────────────────────┘
               │
┌──────────────┴──────────────────────────┐
│   Optional Middleware Layer             │
│   (Add only what you need)              │
│   • Retry     • Caching                 │
│   • Timeout   • Batching                │
│   • Circuit Breaker                     │
└──────────────┬──────────────────────────┘
               │
┌──────────────┴──────────────────────────┐
│   Optional Transport Layer              │
│   • HTTP   • gRPC   • WebSocket         │
└──────────────┬──────────────────────────┘
               │
┌──────────────┴──────────────────────────┐
│   Core Interface (Required)             │
│   • Agent  • Message  • Tool            │
└─────────────────────────────────────────┘

Design Philosophy: Start simple. Add complexity only when you need it.

Learning Path

1. Getting Started (15 min) - Choose your language and create your first agent
   • Python Guide | Go Guide | TypeScript Guide
   • Rust Guide | C++ Guide | Zig Guide
2. Agent Patterns Book (2-3 hours) - Master the 18 core patterns and advanced architectures
3. Advanced Architectures (1 hour) - Pattern compositions and multi-agent systems
4. Examples (1 hour) - Learn by doing with 27+ examples
5. Architecture (30 min) - Understand design principles
6. Migration Guides (30 min per language) - Migrate between languages
7. Production Deployment (1 hour) - Docker + Kubernetes

Total time investment: ~6 hours from zero to production deployment with pattern mastery.

Documentation

Getting Started (Language-Specific)

• Python Guide - 15-30 min to first agent
• Go Guide - Idiomatic Go patterns
• TypeScript Guide - Modern JavaScript/TypeScript
• Rust Guide - Memory-safe agents
• C++ Guide - High-performance systems
• Zig Guide - Systems programming with safety

Patterns & Architecture

• Agent Patterns Book - Comprehensive guide to 18 core patterns
• Advanced Architectures - Pattern compositions and multi-agent systems
• Architecture Principles - Design philosophy
• Streaming Patterns - Language-specific streaming approaches

Migration & Reference

• Migration Guide Index - Complete migration documentation for all 6 languages
• API Reference - Complete API documentation
• Deployment Guide - Docker and Kubernetes
• Examples - 27+ comprehensive examples

Operations & Security

• Security Policy - Vulnerability reporting and best practices
• Compatibility Matrix - Language, platform, and version support
• Testing Strategy - Test philosophy and coverage

Package-Specific Docs

• Memory Management - Context retention strategies
• Budget Tracking - Token and cost management
• Checkpointing - State persistence
• Safety & Security - Input validation
• Evaluation - Quality metrics

Examples

We provide 27+ examples covering common use cases:

Getting Started:

• Basic Agent - Your first agent in 20 lines
• Sequential Pipeline - Chain agents together
• Parallel Execution - Run agents concurrently

Production Features:

• Retry & Circuit Breaker - Handle failures
• Distributed Tracing - Debug with Jaeger
• Rate Limiting - Protect your APIs

Advanced:

• Remote Agents - Cross-process communication
• Streaming Responses - Server-sent events
• Custom Middleware - Extend the toolkit

Browse all examples →

Community

• Website: agenkit.dev
• GitHub: github.com/agenkit/agenkit
• Issues: Report bugs or request features
• Discussions: Ask questions

Contributing

We welcome contributions! See our Contributing Guide.

Development Setup

# Clone repository
git clone https://github.com/agenkit/agenkit.git
cd agenkit

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run type checking
mypy agenkit/

License

Apache License 2.0 - See LICENSE for details.

Status

v0.50.0 - Production Ready! 🚀

Language Support

Language	Patterns	Adapters	Observability	Tests	Status	Performance
Python	18/18 (100%)	6/6 (100%)	✅ Full	470+	✅ Complete	Reference
TypeScript	18/18 (100%)	6/6 (100%)	✅ Full	650+	✅ Complete	Node.js speed
Go	18/18 (100%)	6/6 (100%)	✅ Full	420+	✅ Complete	18x Python
Rust	18/18 (100%)	6/6 (100%)	✅ Full	335+	✅ Complete	20x Python
C++	18/18 (100%)	6/6 (100%)	✅ Full	250+	✅ Complete	25x Python
Zig	18/18 (100%)	6/6 (100%)	✅ Full	335+	✅ Complete	22x Python

18 Core Patterns documented in the Agent Patterns Book: Task, Conversational, ReAct, Planning, Reflection, ReasoningWithTools, AgentsAsTools, Memory, Sequential, Parallel, Router, Fallback, Orchestration, Supervisor, Collaborative, HumanInLoop, MultiAgent, Autonomous

Historic Milestone: First AI agent toolkit to achieve 100% feature parity across 6 languages!

v0.50.0 Release Highlights

• ✅ API Alignment Complete - Consistent parameter naming and validation across all languages
• ✅ Parameter Validation - LLM parameters validated at construction (temperature 0-2, max_tokens >0, top_p 0-1)
• ✅ Timeout Standardization - Clear millisecond units (timeout_ms) in Python, TypeScript, C++, Zig
• ✅ Go Nullable Patterns - Proper pointer types instead of sentinel values
• ✅ Observability Parity - Full OpenTelemetry integration across all 6 languages
• ✅ Language-Specific Guides - Comprehensive getting started documentation for each language
• ✅ Advanced Architecture Docs - Pattern compositions and multi-agent system guidance

Project Status

• ✅ Core toolkit complete across 6 languages
• ✅ 100% Pattern Parity - All 18 patterns in all 6 languages (see book)
• ✅ 100% Adapter Parity - All 6 LLM adapters (OpenAI, Anthropic, Ollama, Bedrock, Gemini, LiteLLM)
• ✅ 100% Observability Parity - OpenTelemetry, W3C Trace Context, distributed tracing
• ✅ 2,100+ tests passing (100% success rate across all 6 languages)
• ✅ Production middleware ready (retry, circuit breaker, timeout, rate limiting, caching, batching)
• ✅ Multiple transports (HTTP/1.1, HTTP/2, HTTP/3, gRPC, WebSocket)
• ✅ Deployment manifests (Docker + Kubernetes with HPA)
• ✅ Comprehensive documentation: 6 language guides + pattern book + advanced architectures
• 🚀 Next: v1.0.0 release (Q1 2026)

---

v0.50.0 Breaking Changes

Python:

• timeout (seconds) → timeout_ms (milliseconds) - Update all timeout parameters
• LLM parameter validation now enforced at construction

Go:

• UserIDExtractor signature changed from func(*Message) string to func(*Message) *string

All other languages: No breaking changes

See language-specific getting started guides for migration examples.

---

Ready to build production AI agents? Visit agenkit.dev or get started in 5 minutes →

Test Parity

Agenkit maintains test parity across all 6 language implementations to ensure consistent behavior and quality. View the Test Parity Dashboard to track progress.

Current Status:

• ✅ Patterns: 100% parity (all 18 patterns implemented)
• 🟡 Go: 51.7% parity (926/1789 tests)
• 🔴 C++: Limited (598 estimated tests)
• 🔴 Rust: 15.4% parity (277/1789 tests)
• 🔴 Zig: 11.9% parity (214/1789 tests)
• 🔴 TypeScript: 18.3% parity (328/1789 tests)

See README-test-parity.md for full documentation.