README
¶
Agenkit Examples
Comprehensive examples demonstrating all Agenkit features across Python and Go.
Running Examples
Python Examples
# Make sure you're in the project directory
cd /path/to/agenkit
# Run any example
python examples/01_basic_agent.py
python examples/middleware/circuit_breaker_example.py
python examples/transport/websocket_example.py
Go Examples
# Navigate to Go examples
cd agenkit-go/examples
# Run any example
go run basic/main.go
go run middleware/circuit_breaker_example.go
go run transport/grpc_example.go
Examples by Category
Core Patterns (6 examples)
01_basic_agent.py
Basic Agent Creation
Learn how to create a simple agent that processes messages.
Key concepts:
- Agent interface
- Message creation
- Async processing
python examples/01_basic_agent.py
02_sequential_pattern.py
Sequential Pattern (Pipeline)
Chain agents in a pipeline where output of one becomes input of next.
Key concepts:
- SequentialPattern
- Validation → Processing → Formatting pipeline
- Error propagation
python examples/02_sequential_pattern.py
03_parallel_pattern.py
Parallel Pattern (Fan-out)
Run multiple agents concurrently on the same input.
Key concepts:
- ParallelPattern
- Concurrent execution
- Result aggregation
- Multiple analysis (sentiment, length, keywords)
python examples/03_parallel_pattern.py
04_router_pattern.py
Router Pattern (Conditional Dispatch)
Route messages to different agents based on content.
Key concepts:
- RouterPattern
- Intent-based routing
- Specialized agents (weather, news, calculator, general)
python examples/04_router_pattern.py
05_tool_usage.py
Tool Usage
Create and use tools within agents.
Key concepts:
- Tool interface
- ToolResult
- Search and calculator tools
- Error handling
python examples/05_tool_usage.py
06_pattern_composition.py
Pattern Composition
Compose patterns to create complex workflows.
Key concepts:
- Patterns of patterns
- Sequential [ Parallel [ ... ], Router { ... } ]
- Metadata propagation
- Multi-stage processing
python examples/06_pattern_composition.py
Transport Layer (3 examples)
transport/websocket_example.py
WebSocket Transport
Bidirectional streaming communication between agents.
Key concepts:
- WebSocket transport protocol
- Real-time bidirectional messaging
- Connection lifecycle management
python examples/transport/websocket_example.py
transport/grpc_example.py
gRPC Transport
High-performance binary protocol for microservices.
Key concepts:
- gRPC transport protocol
- Protocol Buffers serialization
- Cross-language agent communication
python examples/transport/grpc_example.py
Middleware (6 examples)
middleware/circuit_breaker_example.py
Circuit Breaker Middleware
Fail-fast pattern with automatic recovery.
Key concepts:
- Circuit breaker states (closed, open, half-open)
- Failure threshold detection
- Automatic recovery
python examples/middleware/circuit_breaker_example.py
middleware/retry_example.py
Retry Middleware
Exponential backoff with jitter for transient failures.
Key concepts:
- Automatic retry on failure
- Exponential backoff algorithm
- Jitter for distributed systems
python examples/middleware/retry_example.py
middleware/timeout_example.py
Timeout Middleware
Request deadline enforcement.
Key concepts:
- Timeout configuration
- Graceful timeout handling
- Deadline propagation
python examples/middleware/timeout_example.py
middleware/rate_limiter_example.py
Rate Limiter Middleware
Token bucket algorithm for request rate control.
Key concepts:
- Token bucket algorithm
- Rate limiting per time window
- Backpressure handling
python examples/middleware/rate_limiter_example.py
middleware/caching_example.py
Caching Middleware
LRU cache with TTL support.
Key concepts:
- LRU eviction policy
- TTL (time-to-live) expiration
- Cache key generation
python examples/middleware/caching_example.py
middleware/batching_example.py
Batching Middleware
Request aggregation for improved efficiency.
Key concepts:
- Request batching
- Batch size and timeout configuration
- Response distribution
python examples/middleware/batching_example.py
Composition Patterns (4 examples)
composition/sequential_example.py
Sequential Composition
Advanced sequential pattern with error handling.
Key concepts:
- Sequential agent chaining
- Error propagation
- Pipeline composition
python examples/composition/sequential_example.py
composition/parallel_example.py
Parallel Composition
Advanced parallel execution with result aggregation.
Key concepts:
- Concurrent agent execution
- Result aggregation strategies
- Fan-out patterns
python examples/composition/parallel_example.py
composition/fallback_example.py
Fallback Pattern
Automatic fallback to alternative agents on failure.
Key concepts:
- Primary and fallback agents
- Automatic failover
- Resilience patterns
python examples/composition/fallback_example.py
composition/conditional_example.py
Conditional Pattern
Dynamic agent selection based on conditions.
Key concepts:
- Conditional routing
- Dynamic agent selection
- Context-aware execution
python examples/composition/conditional_example.py
Tools (4 examples)
tools/calculator_example.py
Calculator Tool
Mathematical operations tool integration.
Key concepts:
- Tool interface implementation
- Synchronous tool execution
- Error handling
python examples/tools/calculator_example.py
tools/search_example.py
Search Tool
Search functionality integration.
Key concepts:
- Async tool execution
- External API integration
- Result formatting
python examples/tools/search_example.py
tools/database_example.py
Database Tool
Database operations tool integration.
Key concepts:
- Database connections
- Query execution
- Transaction handling
python examples/tools/database_example.py
tools/os_tools_example.py
OS Tools
Operating system operations integration.
Key concepts:
- File system operations
- Process management
- System information
python examples/tools/os_tools_example.py
Adapters (3 examples)
adapters/01_basic_remote_agent.py
Basic Remote Agent
Remote agent communication basics.
Key concepts:
- RemoteAgent wrapper
- Cross-process communication
- Transport abstraction
python examples/adapters/01_basic_remote_agent.py
adapters/02_agent_registry.py
Agent Registry
Centralized agent discovery and management.
Key concepts:
- Agent registration
- Service discovery
- Registry patterns
python examples/adapters/02_agent_registry.py
adapters/03_streaming.py
Streaming Agents
Stream processing with agents.
Key concepts:
- Async streaming
- Backpressure handling
- Stream composition
python examples/adapters/03_streaming.py
Observability (2 examples)
observability/observability_example.py
Full Observability Stack
OpenTelemetry tracing and Prometheus metrics.
Key concepts:
- Distributed tracing with OpenTelemetry
- W3C Trace Context propagation
- Prometheus metrics collection
- Trace correlation
python examples/observability/observability_example.py
middleware/metrics_example.py
Metrics Middleware
Prometheus metrics integration.
Key concepts:
- Metrics middleware
- Custom metric collection
- Metrics export
python examples/middleware/metrics_example.py
Learning Path
We recommend following the examples in this order:
1. Fundamentals
Start with these core examples to understand the basics:
- 01_basic_agent.py - Basic agent creation and message processing
- 02_sequential_pattern.py - Chain agents in a pipeline
- 03_parallel_pattern.py - Run agents concurrently
- 04_router_pattern.py - Conditional agent routing
- 05_tool_usage.py - Tool integration
- 06_pattern_composition.py - Compose patterns together
2. Transport & Remote Agents
Learn cross-process and cross-language communication:
- adapters/01_basic_remote_agent.py - Remote agent basics
- transport/grpc_example.py - gRPC transport
- transport/websocket_example.py - WebSocket transport
- adapters/03_streaming.py - Stream processing
3. Production Middleware
Add resilience and production features:
- middleware/retry_example.py - Retry with exponential backoff
- middleware/timeout_example.py - Timeout enforcement
- middleware/circuit_breaker_example.py - Circuit breaker pattern
- middleware/rate_limiter_example.py - Rate limiting
- middleware/caching_example.py - Response caching
- middleware/batching_example.py - Request batching
4. Observability
Add monitoring and tracing:
- middleware/metrics_example.py - Prometheus metrics
- observability/observability_example.py - Full observability stack
5. Advanced Patterns
Explore advanced composition and tools:
- composition/fallback_example.py - Fallback pattern
- composition/conditional_example.py - Conditional routing
- tools/ - Various tool integrations
Go Examples
All Python examples have Go equivalents in agenkit-go/examples/. The Go examples demonstrate:
- Full Python ↔ Go cross-language compatibility
- Same API patterns and idioms
- Performance-optimized implementations
- Production-ready error handling
Example Go usage:
cd agenkit-go/examples
go run basic/main.go
go run middleware/circuit_breaker_example.go
go run transport/grpc_example.go
Example Statistics
- Total Examples: 26 Python + 16 Go = 42 examples
- Core Patterns: 6 examples
- Transport Layer: 3 examples
- Middleware: 6 examples
- Composition: 4 examples
- Tools: 4 examples
- Adapters: 3 examples
- Observability: 2 examples
Next Steps
- Read the API Documentation for detailed reference
- Check out Architecture for design principles
- See Deployment Guide for Docker/Kubernetes
- Review Observability for monitoring
- Check Performance Benchmarks for metrics
- Explore Cross-Language Integration for Python ↔ Go
Directories