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 configured 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 Builder

Agent.builder() returns an AgentBuilder that can configure the provider, model, instructions, tools, memory, knowledge, retrieval, middleware, hooks, execution configuration, and events. Common builder methods include:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .temperature(0.7)
    .max_tokens(1000)
    .max_tool_iterations(5)
    .tools(add, weather)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .middleware(middleware)
    .hook(my_hook)
    .events(events)
    .build()
)

The builder supports configuration for:

Name
Model
Provider
Instructions
Temperature
Maximum output tokens
Maximum tool iterations
Tools
Memory
Knowledge
Retrievers
Middleware
Hooks
Events

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:

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

The model() method separates the provider name from the model name and resolves the provider through BindAI’s provider system. Current provider integrations include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

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 model configured for the application. The builder also provides a dedicated OpenAI helper:

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

Provider Configuration

Providers can be configured explicitly with provider():

agent = (
    Agent.builder()
    .provider(
        "openai",
        model="gpt-4.1-mini",
    )
    .build()
)

Provider configuration can also include provider-specific settings:

agent = (
    Agent.builder()
    .provider(
        "openai",
        api_key="...",
        endpoint="https://api.openai.com/v1",
        organization="...",
        model="gpt-4.1-mini",
    )
    .build()
)

An already-created ModelProvider can also be supplied:

agent = (
    Agent.builder()
    .provider(provider)
    .build()
)

This allows applications to either use BindAI’s registered provider configuration or supply an existing provider implementation.

Project-Based Provider Configuration

An agent can use project configuration instead of specifying provider settings directly in application code. For example, a project can define:

provider = "openai"
model = "gpt-4.1-mini"
connection = "work"
temperature = 0.7

When the builder has not been given an explicit provider, build() loads the project runtime configuration and uses the configured provider, model, connection, and temperature. The builder can also explicitly load project configuration with from_project():

agent = (
    Agent.builder()
    .from_project(".")
    .build()
)

from_project() loads project-defined tools and provider configuration. This allows an agent definition to remain focused on application behavior while project-level configuration controls provider selection and other runtime settings.

Project-Scoped Provider Connections

A project can select a named provider connection instead of placing provider credentials directly in application code or bindai.toml. For example:

provider = "openai"
model = "gpt-4.1-mini"
connection = "work"

The connection metadata identifies the provider while the credential is stored separately in the operating system credential store. The same connection can be selected directly through the builder:

agent = (
    Agent.builder()
    .model(
        "openai:gpt-4.1-mini",
        connection="work",
    )
    .build()
)

Provider credentials are resolved with the following precedence:

An explicitly supplied API key.
The credential stored for the selected project connection.
The provider’s environment variable.

The configured connection must exist and must match the selected provider. Project-scoped provider connections are documented in the Connections section.

Agent Configuration

Execution behavior can be configured independently from the agent’s identity and capabilities. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .temperature(0.7)
    .max_tokens(1000)
    .max_tool_iterations(5)
    .build()
)

The available builder configuration includes:

temperature() - configures model sampling behavior.
max_tokens() - configures the maximum output token count.
max_tool_iterations() - limits tool execution iterations.

The configuration is stored on the built agent and is used by the execution system. Keeping execution configuration separate from the agent’s identity and capabilities allows the same agent definition to be used with different runtime settings.

Instructions

Instructions define the system-level behavior of an agent. For example:

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

Instructions can also be accessed through the agent:

print(agent.instructions)

The instructions are stored as part of the agent’s prompt configuration.

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() creates the execution context and delegates to the agent’s conversational execution path. The method accepts an optional output type:

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

Chat Execution

BindAI also provides chat() for conversational execution.

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

print(result.output)

run() and chat() currently use the same execution path. run() is the primary application-facing entry point, while chat() makes the conversational nature of the operation explicit. Structured output can also be requested:

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

Conversation state is maintained by the agent’s conversation component and can be combined with configured memory.

Lower-Level Execution

When an application already has an ExecutionContext, it can execute the agent directly:

result = agent.execute(context)

This lower-level interface is useful for framework integrations and components that already manage execution context. The execution context can carry state and variables through the agent execution pipeline.

AgentResult

Agent execution returns an AgentResult.

result = agent.run("Hello!")

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

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

Sending Prompts

The primary execution methods accept a message:

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

The message is placed into the execution context and processed by the agent execution engine. Applications can request structured output by supplying a Python type:

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

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 output type is placed into the execution context and made available to the execution pipeline. 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)

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

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.")
    .tools(add)
    .build()
)

Tools can also be added after construction:

agent.tool(add)

Multiple tools can be registered:

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

The builder provides tools() for registering multiple tools during construction:

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

The builder accepts existing Tool objects as well as callable functions that can be converted into BindAI function tools. add_tool() is available as a backwards-compatible alias for tool().

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. A typical architecture is:

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

Tools are registered in the agent’s ToolRegistry. Applications can also execute a registered tool directly:

result = agent.execute_tool(
    "add",
    a=2,
    b=3,
)

Tool execution can publish a ToolExecutedEvent through the agent event bus.

Memory

Agents have a memory component that is initialized with an in-memory provider by default. A different memory implementation can be attached to an agent:

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()
)

Memory implementations can provide different persistence and retrieval strategies. BindAI supports memory implementations for use cases such as:

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

Memory is separate from the immediate execution input and can be replaced independently from the model provider.

Conversation Context

Agents maintain a Conversation component for conversational state. Conversation context allows an application to work with multiple related messages rather than treating every execution as an isolated request. This is useful for:

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

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

Agent Sessions

Agents provide session() for creating an AgentSession.

session = agent.session()

Sessions provide a higher-level object for applications that need to work with an agent across a sequence of interactions. Use the session abstraction when an application needs session-oriented agent behavior instead of directly managing every execution against the Agent object.

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. BindAI’s knowledge system supports concepts such as:

Document ingestion
Parsing
Chunking
Embeddings
Metadata
Retrieval
Reranking
Conversational retrieval
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 such as:

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()
)

Multiple middleware components can be registered. 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)

Hooks are stored separately from lifecycle callbacks and can be used by application or framework components to participate in agent behavior. These mechanisms can be used for:

Logging
Auditing
Monitoring
Analytics
Notifications
Debugging
Custom application behavior

Events

Agents expose an event bus through agent.events. The event bus can be supplied through the builder:

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

The 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. Tool execution can publish events such as ToolExecutedEvent. The event system is useful for:

Observability
Logging
Metrics
Application events
Debugging
Notifications
Automation integrations

Execution Configuration

Agent execution can be configured independently from the agent’s core identity and capabilities. The current agent configuration includes settings such as:

Temperature
Maximum output tokens
Maximum tool iterations

For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .temperature(0.7)
    .max_tokens(1000)
    .max_tool_iterations(5)
    .build()
)

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 ExecutionContext to carry information associated with an agent execution. Execution context can provide runtime information required by components such as:

Agents
Tools
Middleware
Streaming
Workflows

An agent creates an execution context for normal run() and chat() calls. 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. Structured output configuration is also placed into the execution context before execution.

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 registers the target agent as a tool on the delegating agent. 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.

Agent Teams

BindAI also provides AgentTeam for coordinating a collection of existing agents. A team can register agents directly:

from bindai_agent import AgentTeam

team = AgentTeam(
    name="Research Team",
)

team.add(
    researcher,
    role="research",
)

team.add(
    analyst,
    role="analysis",
)

Agents can then be accessed by name or role:

researcher = team.get("researcher")
research_agent = team.role("research")

The team provides several execution patterns. Sequential team execution:

result = team.run(
    "Research the topic."
)

Chained execution passes each agent’s output to the next agent:

result = team.run_chain(
    "Research and analyze the topic."
)

Parallel execution runs the registered agents concurrently:

result = team.run_parallel(
    "Analyze the topic independently."
)

A team can also continue running after individual failures:

result = team.run_continue(
    "Process this task."
)

Role-based execution is available through methods such as:

team.run_role(
    "research",
    "Research the topic.",
)

and:

team.run_roles_chain(
    ["research", "analysis"],
    "Research and analyze the topic.",
)

AgentTeam is a lightweight coordination abstraction around existing agents. It is distinct from the task-oriented Agent Group system provided by bindai-group.

Agent Groups

BindAI also provides an Agent Group abstraction for coordinating multiple agents around explicit tasks. Agent Groups are useful when the application needs task-oriented multi-agent execution rather than simply running a collection of agents. 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.

Agent Groups and AgentTeam solve different coordination problems:

AgentTeam coordinates an existing collection of agents.
Agent Groups represent explicit tasks assigned to agents.
SequentialProcess and ParallelProcess control group task execution.
Task context can connect dependent tasks.

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 Agent Groups

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 when their 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 depends on Research and therefore cannot begin until its dependency has completed. If multiple tasks have no unresolved dependencies, they can execute concurrently:

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

A later task can then depend on multiple completed tasks:

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

Task dependencies therefore allow parallel processes to combine concurrent work with explicit sequential dependencies.

Handoffs

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 should 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 process-based orchestration, use AgentTeam or Agent Groups depending on the required coordination model.

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.

Team Delegation

Multiple agents can 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

Different BindAI coordination mechanisms can represent this structure. Dynamic delegation through delegate_to() lets one agent invoke another agent as a tool. AgentTeam provides direct coordination of a collection of existing agents. Agent Groups provide explicit task-oriented orchestration. These mechanisms can therefore be selected according to the application’s coordination requirements.

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 AgentTeam.run_chain() or sequential Agent Group tasks. Each stage can receive the output required from the previous stage. This pattern is useful when an application needs predictable specialization rather than entirely dynamic delegation.

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 Teams, Agent Groups, and workflows can be used to make these stages explicit depending on the required orchestration model.

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. Project configuration can also provide provider, model, connection, and temperature settings to AgentBuilder.

Agents and External Integrations

Agents can work with external services through BindAI connections and tools. 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. Project-scoped provider connections are a separate concept from external service connections. Provider connections select credentials for AI model providers, while external service connections represent integrations with application services.

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 MCP integration can provide capabilities such as:

MCP client connections
Tool discovery
Tool calling
MCP tools exposed as BindAI tools
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",
        connection="work",
    )
    .instructions(
        "You are a research assistant. "
        "Use available tools and knowledge to provide "
        "accurate and concise answers."
    )
    .temperature(0.7)
    .max_tool_iterations(5)
    .tools(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

The agent also owns the main runtime components used during execution:

Agent
 |
 +---- Provider
 |
 +---- Prompt / Instructions
 |
 +---- ToolRegistry
 |
 +---- Conversation
 |
 +---- Memory
 |
 +---- Knowledge
 |
 +---- Retriever
 |
 +---- Middleware
 |
 +---- Hooks
 |
 +---- Callbacks
 |
 +---- EventBus
 |
 +---- Execution Configuration
 |
 +---- Execution Engine

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

                  Multi-Agent Application
                           |
            +--------------+--------------+
            |              |              |
            v              v              v
          Agent        AgentTeam      Agent Group
            |              |              |
            v              v              v
          Tools       Coordination       Tasks
                           |              |
                           |              +----> SequentialProcess
                           |              |
                           |              +----> ParallelProcess
                           |
                           v
                       Workflows

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 should 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 AgentTeam when a collection of existing agents should be coordinated directly.
Use Agent Groups when multi-agent work should be represented as explicit tasks.
Use SequentialProcess when group task order or dependencies require sequential execution.
Use ParallelProcess when independent group tasks can safely execute concurrently.
Use task context when one group 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.
Use project configuration when provider and model settings should be managed outside application code.
Use project-scoped provider connections when credentials should remain in the operating system credential store.

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 Builder

​Model Configuration

​Provider Configuration

​Project-Based Provider Configuration

​Project-Scoped Provider Connections

​Agent Configuration

​Instructions

​Running an Agent

​Chat Execution

​Lower-Level Execution

​AgentResult

​Sending Prompts

​Structured Output

​Streaming

​Adding Tools

​Tool Calling

​Memory

​Conversation Context

​Agent Sessions

​Knowledge

​Retrievers

​Retrieval-Augmented Generation

​Middleware

​Hooks and Callbacks

​Events

​Execution Configuration

​Execution Context

​Agent Delegation

​Agent Teams

​Agent Groups

​Sequential Agent Groups

​Parallel Agent Groups

​Handoffs

​Specialist 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 Builder

Model Configuration

Provider Configuration

Project-Based Provider Configuration

Project-Scoped Provider Connections

Agent Configuration

Instructions

Running an Agent

Chat Execution

Lower-Level Execution

AgentResult

Sending Prompts

Structured Output

Streaming

Adding Tools

Tool Calling

Memory

Conversation Context

Agent Sessions

Knowledge

Retrievers

Retrieval-Augmented Generation

Middleware

Hooks and Callbacks

Events

Execution Configuration

Execution Context

Agent Delegation

Agent Teams

Agent Groups

Sequential Agent Groups

Parallel Agent Groups

Handoffs

Specialist 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