Skip to main content

​
General Concepts

Bindu is an AI agent framework for A2A (Agent-to-Agent communication), AP2, and X402 protocols. It handles infrastructure, identity, observability, and payments, turning any local agent script into a production-ready microservice without rewriting code.
The A2A Protocol is a standardized JSON-RPC communication layer. Bindu uses it so agents can communicate, share context, and transfer artifacts regardless of what programming language or framework they were built with.
Use a Workflow for sequential, step-by-step processing within a single agent (e.g., search -> extract -> summarize). Use a Team when you need multiple specialized agents with different identities and tools collaborating on a complex problem.

​
Installation & Setup

Bindu requires Python 3.12 or higher.
Bindu is optimized for the uv package manager. You can install the core framework by running uv add bindu.
Using UV, run uv venv --python 3.12.9. Then activate it using source .venv/bin/activate (macOS/Linux) or .venv\Scripts\activate (Windows) before installing dependencies.
Yes, but UV is strongly recommended. If you use Conda, create your environment (conda create -n bindu-env python=3.12), activate it, and then run pip install uv to manage your Bindu dependencies.
Run uv add bindu --upgrade. Bindu follows semantic versioning, meaning minor and patch updates are backward-compatible.
Partially. Bindu can run entirely locally using InMemoryStorage and local LLMs (like Ollama). However, initial setup (downloading the LLM weights and installing Python packages) requires an internet connection.

​
Environment Variables

Yes. Bindu automatically loads variables from a .env file in your project root.
At a minimum, you must set an API key for your chosen LLM provider (e.g., OPENROUTER_API_KEY, OPENAI_API_KEY, or MINIMAX_API_KEY).
Use the export command in your terminal (e.g., export BINDU_PORT=4000), or add them to your ~/.bashrc or ~/.zshrc file.
In PowerShell, use the $env: prefix (e.g., $env:BINDU_PORT="4000").
Create separate files (e.g., .env.staging and .env.production) and load the specific file in your deployment environment, or inject the variables directly via your CI/CD pipeline.
Yes. You can use the ENV instruction in your Dockerfile, pass them via docker run -e, or use the environment mapping in a docker-compose.yml file.
Bindu delegates API call execution to your driver framework (Agno, LangChain). Most frameworks read the API key at initialization, meaning a restart is usually required unless you implement a custom dynamic key loader in your handler function.

​
Switching Models

Because Bindu is framework-agnostic, you switch providers by changing the model configuration in your underlying framework (e.g., swapping OpenAIChat for Anthropic in Agno) and updating your .env API keys. Bindu’s A2A wrapper does not need to change.
Configure your driver framework to point to your local endpoint (e.g., http://localhost:11434 for Ollama) and pass that agent to Bindu’s bindufy() function.
Yes. You can instantiate multiple agents with different models in your underlying framework (e.g., using AG2 GroupChat) and wrap the final orchestration logic in a single Bindu handler.
Implement a standard try/except fallback loop or use a framework like Tenacity inside your handler function to catch API errors and retry the prompt with a secondary model instance.

​
Agent Communication

Because Bindu uses the standard A2A JSON-RPC protocol, you can use any HTTP client (like httpx or requests) to send a formatted POST request to the external agent’s URL from inside your handler.
Every Bindu agent has a unique Decentralized Identifier (DID). Agents expose their capabilities and DID via a .well-known/agent.json endpoint, allowing for cryptographically verifiable discovery.
Yes. You simply write your LangChain or LangGraph execution logic inside the handler function that you pass to bindufy().
Use the context_id provided in the incoming A2A message payload. Passing this ID to subsequent agents ensures they all read and write to the same conversational memory thread.
The task state transitions to failed. If you are using Bindu’s built-in retry decorators, the framework will automatically attempt to recover using exponential backoff before permanently failing.

​
Memory & State

Bindu supports Task History (A2A message arrays), Context Memory (threaded conversations), and Agent State. It provides InMemoryStorage for testing and PostgresStorage for production.
Set STORAGE_TYPE=postgres and provide a DATABASE_URL in your environment variables. Bindu will automatically persist task histories and contexts.
Bindu delegates Retrieval-Augmented Generation (RAG) to your driver framework. Use tools like Agno’s PDFKnowledgeBase or LangChain’s vector store retrievers inside your handler logic.
Context window management (like sliding windows or token summarization) must be handled by your driver framework before passing the message array to the LLM.

​
Tools & Integrations

Define your custom tools as standard Python functions and provide them to your driver framework’s tool array.
Yes. You can define abstract capabilities in Bindu’s skills/ directory (using YAML or Markdown), which Bindu will advertise publicly. You then implement the actual tools in your handler.
Use the database or vector integrations provided by your driver framework (e.g., LangChain’s SQLDatabaseToolkit or Agno’s PgVector).
If your agent needs human approval, have your handler return a dictionary with "state": "input-required" and a "prompt" asking for clarification. Bindu will pause the task until the user responds.
Bindu delegates this to the driver framework. You can easily attach tools like DuckDuckGoTools or ScrapeGraph to your agent logic.

​
Structured Outputs

Enforce JSON schemas using your driver framework (e.g., Pydantic response_model passing) and ensure your client sends acceptedOutputModes: ["application/json"] in the A2A request configuration.
If the underlying model does not support native JSON mode, you must prompt the model to return JSON text and manually parse/extract it in your handler function.
Use a retry library like Tenacity inside your handler to catch JSON parsing errors or Pydantic ValidationErrors, and feed the error back to the LLM as a retry prompt.

​
Rate Limiting & Cost Management

TPM limits are enforced by your LLM provider (OpenAI, Anthropic). You can resolve this by adding retry logic with exponential backoff to your handler, or switching to an enterprise tier.
Use Bindu’s Redis integration by setting SCHEDULER_TYPE=redis. This allows you to queue tasks and control worker concurrency across distributed instances.
Request caching and token counting must be implemented inside your driver framework’s handler logic before the API call is made.

​
Debugging & Common Errors

Set the environment variable LOGGING__DEFAULT_LEVEL=DEBUG before starting your agent.
This means the client calling your agent provided an expired or invalid Bearer token. You can disable authentication for local development by setting AUTH__ENABLED=false.
Tool looping is a model behavior issue. You can prevent it by setting a maximum tool iteration limit in your driver framework (e.g., max_tool_iterations=5).
This happens when system prompts are ambiguous. Ensure your tool descriptions are highly specific, and use validation inside your handler to catch and reject hallucinated tool calls.
Use Python’s unittest.mock.patch to mock the LLM provider’s response, or build a simple mock handler that returns hardcoded text if a TEST_MODE environment variable is true.
Set TELEMETRY_ENABLED=true and configure the OLTP_ENDPOINT and OLTP_HEADERS in your environment. Bindu will automatically export traces to platforms like Langfuse or Arize.

​
Deployment

Deploy multiple instances of your Bindu agent container behind a load balancer. Point all instances to the same Redis instance (REDIS_URL) and PostgreSQL database (DATABASE_URL) so they can share the task queue and memory state.