Agents

Agents are the core building block of BindAI. An agent combines a language model provider with instructions and optional capabilities such as tools, memory, knowledge, retrieval, middleware, hooks, callbacks, execution configuration, delegation, and multi-agent coordination. Agents provide a consistent interface for executing AI tasks without requiring application code to manage provider-specific execution details.

What Is an Agent?

A BindAI agent is responsible for:

Receiving user input
Executing an AI model
Applying configured instructions
Calling registered tools
Using optional memory
Using optional knowledge or retrieval
Managing conversation context
Applying execution configuration
Running middleware and lifecycle hooks
Returning an AgentResult

The Agent class provides the primary execution interface.

Creating an Agent

The recommended way to create an agent is with Agent.builder().

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The builder provides a fluent interface for configuring the agent before construction. A basic agent can then be executed with:

result = agent.run("Explain what BindAI is.")

print(result.output)

Agent Configuration

Agents can be configured with several capabilities through the builder. Common configuration methods include:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .tool(add)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .middleware(middleware)
    .build()
)

The builder supports configuration for capabilities such as:

Name
Model
Instructions
Tools
Memory
Knowledge
Retrievers
Middleware
Execution configuration
Hooks and callbacks

The fluent API makes it possible to start with a simple agent and add capabilities as an application grows.

Model Configuration

Models are specified using a provider-qualified model name.

provider:model

For example:

.model("openai:gpt-4.1-mini")

Current supported provider integrations include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

The provider registry allows these integrations to share a common application-level interface. For example:

Agent.builder().model("openai:gpt-4.1-mini")

Agent.builder().model("anthropic:claude-sonnet-4")

Agent.builder().model("google:gemini-2.5-flash")

Agent.builder().model("groq:llama-3.3-70b-versatile")

Agent.builder().model("ollama:llama3")

Agent.builder().model("openrouter:openai/gpt-4.1-mini")

Exact model availability depends on the provider and the model configured for the application.

Running an Agent

Use the run() method as the primary application-level execution entry point.

result = agent.run("Explain what BindAI is.")

print(result.output)

run() delegates to the agent’s conversational execution path and returns an AgentResult. You can inspect the result:

print(result.success)

print(result.output)

print(result.error)

A successful execution can therefore be handled consistently regardless of the underlying model provider. For lower-level execution, an existing ExecutionContext can be passed to agent.execute():

result = agent.execute(context)

This is useful when an application or framework component needs direct control over the execution context.

AgentResult

Agent execution returns an AgentResult.

result = agent.run("Hello!")

if result.success:
    print(result.output)
else:
    print(result.error)

The result provides the execution status, generated output, and execution error information when an execution fails. Applications can use the result to determine whether an execution completed successfully before consuming the generated output.

Sending Prompts

The primary execution method accepts a message:

result = agent.run("Explain dependency injection.")

Structured output can also be requested by supplying an output type:

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

This allows applications to request a structured result instead of relying only on free-form text.

Structured Output

BindAI supports structured output using a Python type. For example, a Pydantic model can define the expected result:

from pydantic import BaseModel


class Person(BaseModel):
    name: str
    age: int

Pass the model to run():

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

print(result.output)

The configured model provider is responsible for producing output that can be interpreted according to the supplied type. Structured output is useful when application code needs predictable data rather than unrestricted text.

Streaming

Agents support streaming execution through two interfaces. For normal message-based streaming, use stream_chat():

for chunk in agent.stream_chat("Explain what BindAI is."):
    print(chunk)

When an application already has an ExecutionContext, use stream():

for chunk in agent.stream(context):
    print(chunk)

Streaming is useful for interactive applications that need to process model output progressively rather than waiting for the complete execution. stream_chat() creates the execution context from the supplied message, while stream() operates on an existing execution context.

Chat Execution

BindAI provides chat() for conversational execution.

result = agent.chat("Explain what BindAI is.")

print(result.output)

Structured output can also be requested:

result = agent.chat(
    "Generate a fictional person.",
    output=Person,
)

run() and chat() currently use the same conversational execution path. Use run() as the general application-facing entry point and chat() when the conversational nature of the operation is important to the application. Conversation state can be managed independently through BindAI’s conversation and memory capabilities.

Adding Tools

Agents can execute registered tools. A tool can be attached directly to an agent:

agent.tool(add)

For example:

from bindai import Agent, tool


@tool
def add(a: int, b: int):
    return a + b


agent = (
    Agent.builder()
    .name("calculator")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful calculator assistant.")
    .tool(add)
    .build()
)

The tool becomes available to the agent during execution. Multiple tools can be registered:

agent.tool(add)
agent.tool(weather)
agent.tool(search)

Tools can also be configured through the builder:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .tools(add, weather, search)
    .build()
)

add_tool() is also available as a backwards-compatible alias for tool(). Tool execution is handled through BindAI’s tool registry and execution system.

Tool Calling

When a configured model determines that a tool is required, BindAI can execute the registered tool and incorporate its result into the agent execution. This separates the model-facing tool definition from the application’s tool implementation. A typical architecture is:

User Input
    |
    v
Agent
    |
    v
Language Model
    |
    +----> Tool Call
    |          |
    |          v
    |      Tool Registry
    |          |
    |          v
    |      Tool Execution
    |          |
    |          v
    |      Tool Result
    |
    v
AgentResult

Tool execution results can represent either successful values or execution failures. Failed tool executions retain their error information so the ongoing agent execution can distinguish a tool failure from a successful tool result. This allows agents to interact with application functionality without embedding that functionality directly into prompts.

Memory

Memory is optional and can be attached to an agent.

agent.use_memory(memory)

Memory providers are responsible for storing and retrieving information used by the agent. For example:

from bindai import InMemoryMemory

memory = InMemoryMemory()

agent.use_memory(memory)

Memory can also be configured through the builder:

agent = Agent.builder().name("assistant").model("openai:gpt-4.1-mini").memory(memory).build()

BindAI includes multiple memory implementations, including:

In-memory memory
SQLite memory
PostgreSQL memory
Vector memory
Pinecone-backed memory
Chroma-backed memory
Conversation-oriented memory
Custom memory implementations

Memory is distinct from the agent’s immediate execution input and can be configured independently from the model provider.

Conversation Context

Agents can maintain conversational context through BindAI’s conversation support. Conversation state allows an application to work with multiple related messages rather than treating every execution as an isolated request. This is particularly useful for:

Chat applications
Assistants
Multi-turn workflows
Stateful agent execution
Applications combining conversation history with long-term memory

Conversation management and persistent memory solve related but different problems. Conversation context represents the current conversational interaction, while memory can provide information that persists independently of an individual conversation.

Knowledge

Agents can be connected to knowledge sources.

agent.use_knowledge(knowledge)

Knowledge can also be configured through the builder:

agent = Agent.builder().name("assistant").model("openai:gpt-4.1-mini").knowledge(knowledge).build()

Knowledge integration allows applications to provide external information to agent execution, including Retrieval-Augmented Generation workflows. BindAI’s knowledge system supports document ingestion, parsing, chunking, embeddings, metadata, retrieval, reranking, conversational retrieval, and knowledge pipelines.

Retrievers

A retriever can be attached directly to an agent:

agent.use_retriever(retriever)

Or configured through the builder:

agent = Agent.builder().name("assistant").model("openai:gpt-4.1-mini").retriever(retriever).build()

Retrievers are useful when an application needs to search a knowledge source and provide relevant information to an agent. BindAI supports retrieval strategies including:

Vector retrieval
BM25 retrieval
Hybrid retrieval

Retrieval can therefore combine semantic similarity with lexical matching depending on the application’s requirements.

Retrieval-Augmented Generation

An agent can use retrieved knowledge as additional context during execution. A typical RAG flow is:

User Question
      |
      v
Retriever
      |
      v
Relevant Knowledge
      |
      v
Agent Context
      |
      v
Language Model
      |
      v
AgentResult

This allows the model to answer using information retrieved from an application’s knowledge sources. RAG-enabled agents can also participate in larger workflows and multi-agent systems.

Middleware

Middleware can be attached to an agent using:

agent.use_middleware(middleware)

The builder provides the corresponding configuration method:

agent = (
    Agent.builder().name("assistant").model("openai:gpt-4.1-mini").middleware(middleware).build()
)

Middleware provides reusable behavior around agent execution. Typical applications include:

Logging
Authentication
Telemetry
Metrics
Request processing
Response processing
Cross-cutting application behavior

Middleware is useful when behavior should be shared across agents rather than implemented separately in every agent.

Hooks and Callbacks

Agents expose lifecycle and callback mechanisms that allow applications to react to execution events. Agents provide callback registration through on():

def before_run(agent, context):
    print("Agent execution started.")


agent.on("before_run", before_run)

The built-in lifecycle callback events include:

before_run
after_run
error

For example:

def after_run(agent, context, result):
    print("Execution completed:", result.success)


def on_error(agent, context, error):
    print("Execution failed:", error)


agent.on("after_run", after_run)
agent.on("error", on_error)

Agents also support hooks through:

agent.hook(my_hook)

These mechanisms can be used for:

Logging
Auditing
Monitoring
Analytics
Notifications
Debugging
Custom application behavior

Hooks and callbacks are useful when application behavior needs to observe or participate in agent execution.

Events

Agents expose an event bus through agent.events. Tool execution publishes framework events such as ToolExecutedEvent:

agent.events.subscribe(
    "tool.executed",
    handle_tool_event,
)

This event bus is separate from the agent’s callback mechanism. The agent callback API uses:

agent.on("before_run", callback)
agent.on("after_run", callback)
agent.on("error", callback)

The event bus uses event subscriptions and published event objects:

Agent
  |
  +----> Lifecycle callbacks
  |
  +----> EventBus
             |
             +----> Event subscribers

The event system is useful for:

Observability
Logging
Metrics
Application events
Debugging
Notifications
Automation integrations

The lower-level BindAI event system can also be used by automation triggers to react to framework events without coupling automation logic directly to an agent implementation.

Execution Configuration

Agent execution can be configured independently from the agent’s core identity and capabilities. Execution configuration can be used to control aspects of execution such as:

Tool execution behavior
Maximum tool iterations
Execution limits
Timeout-related behavior
Other runtime execution settings

Keeping execution configuration separate from the agent’s core definition allows applications to reuse the same agent configuration in different execution environments.

Execution Context

BindAI uses execution context to carry information associated with an agent execution. Execution context can provide the runtime information required by execution components such as:

Agents
Tools
Middleware
Streaming
Workflows

This allows execution-related state and configuration to move through the framework without requiring every component to manage its own independent state. Agents can also execute directly from an existing context:

result = agent.execute(context)

This lower-level interface is useful for framework integrations and components that already manage an execution context.

Agent Delegation

Agents can delegate work to other agents through delegate_to().

researcher = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .instructions("Research topics and summarize findings.")
    .build()
)

assistant = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("Coordinate work and use specialists when appropriate.")
    .build()
)

assistant.delegate_to(researcher)

Delegation exposes the target agent to the delegating agent as a tool. An optional name and description can be supplied:

assistant.delegate_to(
    researcher,
    name="research",
    description="Research a topic and return a concise summary.",
)

A typical delegation pattern is:

Primary Agent
      |
      +----> Research Agent
      |
      +----> Writing Agent
      |
      +----> Analysis Agent

Each specialist can focus on a narrower responsibility while the primary agent coordinates the overall task. Delegation helps keep individual agents focused and makes larger systems easier to compose.

Agent Handoff

BindAI can also be used to implement handoff patterns between specialized agents. A handoff allows responsibility for a task to move from one agent to another when another specialist is better suited to continue the execution. A typical pattern is:

General Assistant
        |
        v
   Handoff Decision
      /       \
     v         v
Research    Support
  Agent       Agent

Handoffs are useful for applications where different agents have clearly separated responsibilities. For explicit multi-agent execution with task dependencies and shared group orchestration, use Agent Groups.

Specialist Agents

Specialist agents can be created around specific roles. Examples include:

Research agents
Writing agents
Coding agents
Analysis agents
Support agents
Retrieval-focused agents

A specialist should generally have focused instructions, appropriate tools, and only the knowledge or memory required for its responsibility. This keeps multi-agent systems modular and easier to maintain.

Agent Groups

BindAI provides an Agent Group abstraction for coordinating multiple agents around a collection of tasks. Agent Groups are useful when the application needs explicit task-oriented multi-agent execution rather than asking one agent to dynamically delegate every operation. The public group API is provided by bindai-group. A basic group can be created with GroupBuilder:

from bindai_group import GroupBuilder, Task

group = (
    GroupBuilder()
    .name("Research Team")
    .agent(researcher)
    .agent(writer)
    .task(
        Task(
            description="Research the topic.",
            agent=researcher,
        )
    )
    .task(
        Task(
            description="Write a report based on the research.",
            agent=writer,
        )
    )
    .build()
)

result = group.run()

print(result.success)
print(result.output)

The main group components are:

Group - represents the agent group and its tasks.
GroupBuilder - provides the fluent construction API.
Task - describes work assigned to a specific agent.
GroupResult - contains the overall group execution result.
SequentialProcess - executes tasks sequentially.
ParallelProcess - executes independent tasks concurrently.

Sequential Agent Groups

The default group process is sequential execution.

from bindai_group import GroupBuilder, Task

group = (
    GroupBuilder()
    .name("Research Pipeline")
    .agent(researcher)
    .agent(writer)
    .task(
        Task(
            description="Research the topic.",
            agent=researcher,
        )
    )
    .task(
        Task(
            description="Write the final report.",
            agent=writer,
        )
    )
    .build()
)

Sequential groups execute tasks in their configured order. Task dependencies can provide previous task results as context:

research = Task(
    description="Research the topic.",
    agent=researcher,
)

report = Task(
    description="Write a report using the research.",
    agent=writer,
).context_from(research)

The dependent task can then use the previous task’s result as context during execution.

Parallel Agents

Independent Agent Group tasks can be executed concurrently using ParallelProcess.

from bindai_group import GroupBuilder, ParallelProcess, Task

group = (
    GroupBuilder()
    .name("Parallel Research Team")
    .process(ParallelProcess())
    .agent(researcher)
    .agent(analyst)
    .task(
        Task(
            description="Research the topic.",
            agent=researcher,
        )
    )
    .task(
        Task(
            description="Analyze the topic independently.",
            agent=analyst,
        )
    )
    .build()
)

result = group.run()

Independent tasks can run at the same time, reducing total execution time when the work can safely be performed concurrently. The parallel process also respects task dependencies. For example:

research = Task(
    description="Research the topic.",
    agent=researcher,
)

analysis = Task(
    description="Analyze the research.",
    agent=analyst,
).context_from(research)

Here:

Research
   |
   v
Analysis

Analysis does not start until Research has completed successfully. If multiple tasks have no unresolved dependencies, they can execute concurrently:

          +----> Research
          |
Start ----+
          |
          +----> Analysis
          |
          +----> Fact Check

A later task can then depend on one or more completed tasks:

Research --------+
                 |
Analysis --------+----> Final Report
                 |
Fact Check ------+

The parallel process preserves configured task order when assembling the final group output even though independent tasks may complete in a different order. If a task fails, the group fails and dependent work is not started.

Team Delegation

Multiple agents can also participate in team-oriented execution. A team can divide a larger task between agents with different responsibilities. For example:

                    Team
                     |
         +-----------+-----------+
         |           |           |
         v           v           v
      Research    Analysis    Writing
       Agent        Agent       Agent

Agent Groups provide an explicit mechanism for organizing this type of task-oriented team execution. Dynamic delegation through delegate_to() and explicit Agent Groups solve related but different coordination problems:

delegate_to() lets an agent dynamically invoke another agent as a tool.
Agent Groups provide explicit tasks and process-based orchestration.
ParallelProcess allows independent group tasks to execute concurrently.
Task context allows dependent tasks to consume previous task results.

Specialist Role Chains

Specialists can also be organized into role-oriented execution chains. For example:

Research
   |
   v
Analysis
   |
   v
Writing
   |
   v
Final Response

This can be implemented with sequential Agent Group tasks and task dependencies. Each role can receive the output or context required from the previous stage. This pattern is useful when an application needs predictable specialization rather than an entirely free-form team.

RAG-Enabled Multi-Agent Systems

Knowledge and retrieval capabilities can be combined with delegation and specialist agents. For example:

                 Primary Agent
                      |
              +-------+-------+
              |               |
              v               v
        Research Agent   Analysis Agent
              |               |
              v               v
          Retriever        Knowledge
              |               |
              +-------+-------+
                      |
                      v
                 Final Agent

This allows different agents to use different knowledge sources or retrieval strategies while participating in the same larger application. Agent Groups can also be used to make these stages explicit and provide task dependencies between them.

Agents in Workflows

Agents can be used as components within larger BindAI workflows. A workflow can coordinate agents with operations such as:

Conditions
Loops
Parallel execution
Retries
Timeouts
Human tasks
Scheduling

This makes it possible to keep individual agents focused on specific responsibilities while using workflows for higher-level orchestration. For example:

Workflow
   |
   +----> Research Agent
   |
   +----> Condition
   |
   +----> Analysis Agent
   |
   +----> Human Approval
   |
   +----> Final Agent

Workflows are therefore useful when execution involves multiple explicit stages or control-flow decisions.

Agents in Projects

Agents can be organized as part of a BindAI project. A project can provide the surrounding application structure for:

Agents
Tools
Workflows
Knowledge
Memory
Templates
Tests
Configuration

This allows agent definitions to remain focused on agent behavior while the project organizes the broader application.

Agents and External Integrations

Agents can work with external services through BindAI connections. Current connection integrations include:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

Connections provide application-level access to external services, while tools can expose that functionality to an agent when appropriate. This makes it possible to build agents that interact with external systems without embedding provider-specific integration logic directly into the agent.

Agents and MCP

BindAI also supports MCP connections and MCP-discovered tools. MCP integrations can provide agents with access to tools exposed by MCP-compatible services. The current MCP integration supports:

MCP client connections
Tool discovery
Tool calling
MCP tools exposed as BindAI tools
Basic connection handling

This provides another way to extend an agent’s capabilities beyond locally defined tools.

Building a Complete Agent

A more complete agent can combine several capabilities:

from bindai import Agent

agent = (
    Agent.builder()
    .name("research-assistant")
    .model("openai:gpt-4.1-mini")
    .instructions(
        "You are a research assistant. "
        "Use available tools and knowledge to provide "
        "accurate and concise answers."
    )
    .tool(search)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .middleware(middleware)
    .build()
)

The same agent can then be executed through the standard interface:

result = agent.run("Research the latest information about BindAI.")

print(result.output)

The important principle is that capabilities remain composable. An application can add tools, memory, knowledge, retrieval, middleware, callbacks, and multi-agent behavior without replacing the fundamental agent execution interface.

Agent Architecture

A typical BindAI agent can be viewed as several layers:

                         Agent
                           |
       +-------------------+-------------------+
       |                   |                   |
       v                   v                   v
 Instructions            Tools              Context
                                               |
                                    +----------+----------+
                                    |                     |
                                    v                     v
                                  Memory              Knowledge
                                                          |
                                                          v
                                                      Retriever

       |
       v

 Middleware / Hooks / Callbacks / Events

       |
       v

 Execution Configuration

       |
       v

 Model Provider

       |
       v

 AgentResult

For multi-agent applications, the agent can also participate in higher-level coordination:

                     Multi-Agent Application
                              |
             +----------------+----------------+
             |                |                |
             v                v                v
          Agent           Agent Group      Workflow
             |                |                |
             v                v                v
          Tools         Tasks / Processes   Control Flow
             |                |                |
             +----------------+----------------+
                              |
                              v
                         Agent Results

This separation keeps agent behavior modular and allows different applications to compose the capabilities they need.

Best Practices

Give each agent a clear responsibility.
Keep instructions focused.
Prefer reusable tools over increasingly complex prompts.
Use memory for information that must persist beyond a single execution.
Use knowledge and retrievers for external information.
Use middleware for reusable cross-cutting behavior.
Use hooks and callbacks for lifecycle behavior.
Use the event system for event-driven application integration and observability.
Use execution configuration for runtime behavior rather than embedding runtime concerns in prompts.
Use specialist agents when responsibilities are clearly separated.
Use delegate_to() when an agent should dynamically invoke another specialist.
Use Agent Groups when multi-agent work should be represented as explicit tasks.
Use SequentialProcess when task order matters.
Use ParallelProcess when independent tasks can safely execute concurrently.
Use task context when one task depends on the result of another.
Use workflows when multiple agents or execution stages need explicit orchestration and control flow.
Keep external integrations behind connections or tools.
Use MCP when an external MCP service provides capabilities that should be exposed to the agent.

The result is a modular architecture where individual agents remain focused while larger AI applications can be composed from reusable agents, tools, knowledge sources, workflows, connections, and integrations.

​Agents

​What Is an Agent?

​Creating an Agent

​Agent Configuration

​Model Configuration

​Running an Agent

​AgentResult

​Sending Prompts

​Structured Output

​Streaming

​Chat Execution

​Adding Tools

​Tool Calling

​Memory

​Conversation Context

​Knowledge

​Retrievers

​Retrieval-Augmented Generation

​Middleware

​Hooks and Callbacks

​Events

​Execution Configuration

​Execution Context

​Agent Delegation

​Agent Handoff

​Specialist Agents

​Agent Groups

​Sequential Agent Groups

​Parallel Agents

​Team Delegation

​Specialist Role Chains

​RAG-Enabled Multi-Agent Systems

​Agents in Workflows

​Agents in Projects

​Agents and External Integrations

​Agents and MCP

​Building a Complete Agent

​Agent Architecture

​Best Practices

Agents

What Is an Agent?

Creating an Agent

Agent Configuration

Model Configuration

Running an Agent

AgentResult

Sending Prompts

Structured Output

Streaming

Chat Execution

Adding Tools

Tool Calling

Memory

Conversation Context

Knowledge

Retrievers

Retrieval-Augmented Generation

Middleware

Hooks and Callbacks

Events

Execution Configuration

Execution Context

Agent Delegation

Agent Handoff

Specialist Agents

Agent Groups

Sequential Agent Groups

Parallel Agents

Team Delegation

Specialist Role Chains

RAG-Enabled Multi-Agent Systems

Agents in Workflows

Agents in Projects

Agents and External Integrations

Agents and MCP

Building a Complete Agent

Agent Architecture

Best Practices