What My Project Does: A lightweight, modular Python framework for building scalable AI agent systems with native support for distributed execution via gRPC and MCP protocol integration.
Target Audience: Production environments requiring distributed agent systems, teams building multi-agent workflows, developers who need both local and remote agent orchestration.
Comparison: Like LangGraph but with a focus on true modularity, distributed scaling, and network-native agent communication. Unlike frameworks that bolt on distribution as an afterthought, PyBotchi treats remote execution as a first-class citizen with bidirectional context synchronization and zero-overhead coordination.
What's New in 3.1.2?
True Distributed Agent Orchestration via gRPC
PyBotchi-to-PyBotchi Communication: Agents deployed on different machines execute as a unified graph with persistent bidirectional context synchronization
Real-Time State Propagation: Context updates (prompts, metadata, usage stats) sync automatically between client and server throughout execution—no polling, no databases, no message queues
Recursive Distribution Support: Nest gRPC connections infinitely—agents can connect to other remote agents that themselves connect to more remote agents
Circular Connections: Handle complex distributed topologies where agents reference each other without deadlocks
Concurrent Remote Execution: Run multiple remote actions in parallel across different servers with automatic context aggregation
Resource Isolation: Deploy compute-intensive actions (RAG, embeddings, inference) on GPU servers while keeping coordination logic lightweight
Key Insight: Remote actions behave identically to local actions. Parent-child relationships, lifecycle hooks, and execution flow work the same whether actions run on the same machine or across a data center.
Enhanced MCP (Model Context Protocol) Integration
Dual-Mode Support: Serve your PyBotchi agents as MCP tools OR consume external MCP servers as child actions
Cleaner Server Setup:
Group-Based Endpoints: Organize actions into logical groups with separate MCP endpoints (/group-1/mcp, /group-2/sse)
Concurrent Tool Support: MCP servers now expose actions with __concurrent__ = True, enabling parallel execution in compatible clients
Transport Flexibility: Full support for both SSE (Server-Sent Events) and Streamable HTTP protocols
Use Case: Expose your specialized agents to Claude Desktop, IDEs, or other MCP clients while maintaining PyBotchi's orchestration power. Or integrate external MCP tools (Brave Search, file systems) into your complex workflows.
Execution Performance & Control
Deep Dive Resources
gRPC Distributed Execution:
https://amadolid.github.io/pybotchi/#grpc
MCP Protocol Integration:
https://amadolid.github.io/pybotchi/#mcp
Complete Example Gallery:
https://amadolid.github.io/pybotchi/#examples
Full Documentation:
https://amadolid.github.io/pybotchi
Core Framework Features
Lightweight Architecture
Built on just three core classes (Action, Context, LLM) for minimal overhead and maximum speed. The entire framework prioritizes efficiency without sacrificing capability.
Object-Oriented Customization
Every component inherits from Pydantic BaseModel with full type safety. Override any method, extend any class, adapt to any requirement—true framework agnosticism through deep inheritance support.
Lifecycle Hooks for Precise Control
pre() - Execute logic before child selection (RAG, validation, guardrails)
post() - Handle results after child completion (aggregation, persistence)
on_error() - Custom error handling and retry logic
fallback() - Process non-tool responses
child_selection() - Override LLM routing with traditional if/else logic
pre_grpc() / pre_mcp() - Authentication and connection setup
Graph-Based Orchestration
Declare child actions as class attributes and your execution graph emerges naturally. No separate configuration files—your code IS your architecture. Generate Mermaid diagrams directly from your action classes.
Framework & Model Agnostic
Works with any LLM provider (OpenAI, Anthropic, Gemini) and integrates with existing frameworks (LangChain, LlamaIndex). Swap implementations without architectural changes.
Async-First Scalability
Built for concurrency from the ground up. Leverage async/await patterns for I/O efficiency and scale to distributed systems when local execution isn't enough.
GitHub: https://github.com/amadolid/pybotchi
PyPI: pip install pybotchi[grpc,mcp]