Execution

Execution is the process BindAI uses to run an agent against an input and produce a result. An execution can involve the configured model, instructions, tools, memory, knowledge, retrieval, middleware, conversation context, execution configuration, and event handling depending on how the agent is configured. The main application-facing execution interface is the agent’s run() method.

Running an Agent

A basic execution starts with agent.run():

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

print(result.output)

The primary execution call accepts a message and can optionally receive an output type for structured results:

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

The first argument is the user message. The optional output argument specifies a Python type for structured output.

Execution Result

agent.run() returns an AgentResult.

result = agent.run("Hello!")

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

The result provides a consistent interface for checking whether execution succeeded and accessing the generated output or error. A typical application can therefore use:

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

This keeps application-level result handling independent of the underlying model provider.

Structured Output

Execution can return structured results instead of plain text. For example, a Pydantic model can define the expected structure:

from pydantic import BaseModel


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

Pass the type to run():

result = agent.run(
    "Generate a fictional user.",
    output=User,
)

print(result.output)

The application can then work with the structured result rather than parsing raw text manually. Structured output is useful when downstream application code requires predictable data.

Tool Execution

Agents can be configured with tools. For example:

from bindai import Agent

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

Tools become part of the agent’s execution capabilities. A model may request a registered tool during execution. BindAI then executes the requested tool and feeds the resulting tool message back into the ongoing agent execution. Conceptually:

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

The model can therefore perform multiple tool/model interaction cycles during a single agent execution.

Advanced Tool Execution

BindAI’s tool execution pipeline supports multiple tool calls within an execution and feeds their results back into the conversation used for the next model request. When a model requests tools, BindAI:

Records the assistant’s tool-call message.
Executes the requested tools.
Records each tool result.
Builds the next model request from the updated conversation.
Continues the execution pipeline.
Produces the final AgentResult when execution completes.

Conceptually:

Model Response
     |
     v
Tool Calls
     |
     +--------+
     |        |
     v        v
 Tool A    Tool B
     |        |
     v        v
 Result A  Result B
     |        |
     +--------+
          |
          v
Updated Conversation
          |
          v
     Next Model Call
          |
          v
      Final Result

This allows an agent to perform multi-step tool interactions rather than treating a tool call as the end of execution.

Multiple Tool Calls

A model response can request multiple tools during the same execution step. For example:

Model
 |
 +----> Search Tool
 |
 +----> Calculator Tool
 |
 +----> Database Tool

BindAI executes each requested tool and adds the resulting tool messages to the conversation. The next model request can then use the combined results to continue reasoning about the task. The exact number and order of tool interactions depend on the model response, configured tools, execution settings, and application requirements.

Tool Execution Failures

Tool execution can fail. A failed tool execution is preserved as an explicit tool result rather than being silently represented as a successful value. For example, if a tool returns an execution error:

Tool execution failed: connection timeout

the error information is added to the conversation so the model can receive that failure as part of the next execution step. Conceptually:

Model
  |
  v
Tool Call
  |
  v
Tool Execution
  |
  X
Failure
  |
  v
Tool Error Result
  |
  v
Next Model Request

This is important because a tool failure is different from a successful tool call whose result happens to contain an error-like value. The agent can therefore continue execution with knowledge that the requested operation failed. For example, the model may:

Retry the operation through another tool call.
Adjust the request.
Explain the failure to the user.
Continue using information already available.
Stop execution when the failure prevents useful progress.

The application’s final behavior still depends on the model and configured execution limits.

Tool Iterations

Tool-using agents may perform multiple model/tool interaction cycles during a single execution. BindAI provides execution configuration for controlling runtime behavior such as tool execution limits. For example, when an agent is configured with a maximum tool-iteration setting, the application can prevent an execution from continuing indefinitely through repeated tool interactions. The appropriate limit depends on the application’s requirements and the complexity of the tools being used. Tool iteration limits are especially useful for agents that:

Use multiple tools
Perform multi-step tool calls
Depend on external services
Need predictable execution boundaries

A typical execution can therefore look like:

Iteration 1
    Model
      |
      v
   Tool Call
      |
      v
   Tool Result
      |
      v

Iteration 2
    Model
      |
      v
   Tool Call
      |
      v
   Tool Result
      |
      v

Iteration 3
    Model
      |
      v
 Final Response

Memory

Memory can be attached to an agent:

agent.use_memory(memory)

Or configured when building the agent:

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

Memory is an optional execution capability. It can provide stored information to an agent when the configured memory implementation supports it. BindAI supports multiple memory implementations, including in-memory, SQLite, PostgreSQL, vector, Pinecone, and Chroma-backed memory.

Conversation Context

Agent execution can also incorporate conversation context. Conversation support is useful when an application needs to preserve the relationship between multiple messages. A conversational execution can conceptually combine:

Agent Instructions
        +
Conversation Context
        +
Current User Input
        +
Optional Memory / Knowledge
        =
Model Execution

Conversation context and long-term memory are related but distinct. Conversation represents the current interaction, while memory can provide information that persists independently of a particular conversation. Tool calls and tool results are also represented in the conversation used by the execution pipeline, allowing subsequent model iterations to receive the results of previous tool operations.

Knowledge

Knowledge can also be attached to an agent:

agent.use_knowledge(knowledge)

Or configured through the builder:

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

Knowledge systems allow applications to provide external information to agent execution. BindAI’s knowledge capabilities include document ingestion, parsing, chunking, embeddings, metadata, retrieval, reranking, conversational retrieval, and knowledge pipelines. The exact retrieval behavior depends on the configured knowledge and retrieval components.

Retrievers

Agents can use a retriever directly:

agent.use_retriever(retriever)

The builder provides the corresponding configuration:

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

Retrievers are useful when an application needs to locate relevant information for an agent. BindAI supports retrieval strategies including:

Vector retrieval
BM25 retrieval
Hybrid retrieval

Retrieved information can then be incorporated into agent execution as relevant context.

Retrieval-Augmented Generation

Knowledge and retrieval can be combined with agent execution to implement Retrieval-Augmented Generation. A typical execution flow is:

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

This allows an agent to use information retrieved from an application’s knowledge sources rather than relying only on the model’s existing knowledge.

Middleware

Middleware provides reusable execution behavior. Attach middleware directly:

agent.use_middleware(middleware)

Or configure it through the builder:

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

Middleware is useful for cross-cutting concerns such as:

Logging
Authentication
Telemetry
Metrics
Request processing
Response processing
Other reusable execution behavior

Middleware allows these concerns to remain separate from the core agent instructions and application logic.

Execution Context

Some BindAI execution APIs operate with an ExecutionContext. For example, the low-level stream() API accepts an execution context:

agent.stream(context)

The execution context provides runtime information required by the relevant execution operation. Context-aware APIs are particularly useful when integrating agents with larger application or workflow runtimes. Execution context helps execution components share runtime state without requiring every component to maintain independent state. The standard message-based methods such as run(), chat(), and stream_chat() create the execution context internally.

Streaming

BindAI exposes streaming APIs for execution. The low-level stream() method accepts an ExecutionContext:

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

For conversational applications, BindAI also provides stream_chat():

for chunk in agent.stream_chat("Explain neural networks."):
    print(chunk)

stream_chat() creates the execution context from the supplied message, while stream() operates on an existing execution context. Streaming is useful when an application needs to process output progressively. Common use cases include:

Chat interfaces
Interactive applications
Long-running responses
Real-time user interfaces

Streaming is different from normal run() execution because the application can consume output as it becomes available.

Chat Execution

BindAI also provides a chat() method:

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

print(result.output)

Like run(), chat() can accept an optional structured-output type:

result = agent.chat(
    "Generate a fictional user.",
    output=User,
)

run() currently delegates to the same conversational execution path used by chat(). Use the execution interface that best matches the application’s interaction model. For conversational applications, chat() can be combined with BindAI’s conversation and memory capabilities.

Events

Agents expose an event bus through agent.events. For example, an application can subscribe to tool execution events:

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

The agent publishes a ToolExecutedEvent after a tool execution completes. The event bus is distinct from the agent’s lifecycle callback API. The agent callback API uses:

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

The event bus uses event objects and subscriptions:

Agent
  |
  +----> Lifecycle Callbacks
  |
  +----> EventBus
             |
             +----> Event Subscribers

The event system can be used for:

Monitoring
Logging
Analytics
Auditing
Observability
Notifications
Automation integrations

Automation triggers can use the event bus to react to framework events without coupling automation logic directly to an agent’s internal execution implementation.

Hooks and Callbacks

Agents expose lifecycle and callback mechanisms for execution-related behavior. The built-in lifecycle callbacks are:

before_run
after_run
error

For example:

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


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


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


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

These mechanisms can be used around agent execution for purposes such as:

Custom logging
Notifications
Auditing
Metrics
External integrations
Debugging

Hooks can also be registered through:

agent.hook(my_hook)

Hooks should generally remain focused on cross-cutting behavior rather than containing the application’s core business logic. This keeps the execution lifecycle separate from the primary responsibilities of the agent.

Execution Configuration

BindAI supports execution configuration for controlling runtime behavior. Execution configuration can be used for concerns such as:

Tool execution limits
Execution boundaries
Runtime options
Other agent execution settings

Execution configuration should be kept separate from behavioral instructions whenever possible. For example, an instruction should describe what an agent should do, while an execution setting can control how the runtime limits or manages that work. This separation makes the same agent configuration easier to reuse in different environments.

Execution and Projects

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

Agents
Tools
Workflows
Knowledge
Memory
Templates
Tests
Application configuration

The recommended agent API is Agent.builder() rather than relying on an undocumented project-loading constructor. For example:

from bindai import Agent

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

Project organization can then keep agent construction and broader application configuration separate.

Execution and Workflows

Agents can participate in larger workflows. A workflow can coordinate agent execution with operations such as:

Conditions
Loops
Parallel execution
Retries
Timeouts
Human tasks
Scheduling

This allows individual agents to remain focused on specific responsibilities while workflows handle higher-level orchestration. Conceptually:

Workflow
    |
    +----> Agent
    |
    +----> Condition
    |
    +----> Agent
    |
    +----> Human Task
    |
    +----> Final Result

A workflow is useful when execution requires multiple explicit stages or control-flow decisions.

Execution and Multi-Agent Systems

Agent execution can also be combined with delegation and multi-agent patterns. A primary agent can delegate work to specialist agents:

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

Each specialist can perform its own execution while the larger system coordinates the overall task. BindAI also supports Agent Groups for explicit task-oriented multi-agent execution. Agent Groups can use sequential or parallel processes:

Agent Group
     |
     +----> Task A
     |
     +----> Task B
     |
     +----> Task C

With a parallel process, independent tasks can execute concurrently:

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

Tasks can also declare dependencies:

Research
   |
   v
Analysis
   |
   v
Final Report

A dependent task waits until its required context tasks have completed successfully. This makes Agent Groups useful when multi-agent execution needs explicit task structure rather than relying entirely on dynamic agent delegation.

Execution and External Tools

Agent execution can interact with external systems through tools and connections. Current BindAI connection integrations include:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

Connections provide integration infrastructure, while tools can expose appropriate external operations to an agent. This keeps external service logic separate from the agent’s core execution behavior.

Execution and MCP

BindAI also supports MCP connections and MCP-discovered tools. MCP tools can become part of an agent’s available execution capabilities. The current MCP integration supports:

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

This allows an agent to use capabilities provided by compatible MCP services.

Error Handling

Always check the returned AgentResult when application behavior depends on successful execution.

result = agent.run("Perform the requested operation.")

if not result.success:
    print("Execution failed:")
    print(result.error)
else:
    print(result.output)

This keeps application-level error handling independent from provider-specific response formats. Applications should decide how execution failures are surfaced, retried, logged, or returned to users based on their requirements. Tool execution failures are handled separately inside the tool-execution cycle. The failure is preserved as tool-result information so the model can receive the failure and decide how to continue.

Execution Boundaries

Agent execution can involve multiple components:

Input
  |
  v
Agent
  |
  +---- Instructions
  |
  +---- Conversation
  |
  +---- Memory
  |
  +---- Knowledge / Retrieval
  |
  +---- Tools
  |
  +---- Middleware
  |
  v
Model Provider
  |
  v
AgentResult

When tools are involved, execution can contain additional model/tool cycles:

Input
  |
  v
Model
  |
  v
Tool Call
  |
  v
Tool Execution
  |
  v
Tool Result
  |
  v
Model
  |
  v
Final Result

Keeping these responsibilities separate makes execution easier to understand and maintain. For example:

Instructions define behavior.
Conversation provides interaction context.
Memory provides persisted information.
Knowledge and retrieval provide external information.
Tools provide actions.
Middleware provides reusable execution behavior.
The model provider performs model inference.
AgentResult provides the application-facing result.

A Complete Execution Example

The following example combines basic agent execution with a tool:

from bindai import Agent


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

        Use available tools when they are useful.
        Provide clear and concise answers.
        """
    )
    .tool(search)
    .build()
)

result = agent.run("Find information about BindAI.")

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

During execution, the model may request the search tool. BindAI executes the tool, records its result, and continues the model execution with the updated conversation. The same agent can later be extended with additional capabilities:

agent.tool(calculator)
agent.use_memory(memory)
agent.use_knowledge(knowledge)
agent.use_retriever(retriever)
agent.use_middleware(middleware)

This allows the execution layer to grow with the application while keeping the primary agent interface consistent.

Execution Best Practices

Use run() for general agent execution.
Use chat() for conversational execution.
Use streaming when output needs to be processed progressively.
Use structured output when downstream code requires predictable data.
Configure reasonable execution and tool limits for tool-using agents.
Treat tool failures as execution information rather than assuming every tool call succeeds.
Use memory when persisted information is required.
Use knowledge and retrievers for external information.
Use middleware for reusable cross-cutting behavior.
Use hooks and callbacks for lifecycle integrations.
Use the event bus for event-driven integrations and observability.
Check AgentResult.success when execution failure needs to be handled explicitly.
Keep runtime configuration separate from behavioral instructions.
Use workflows when multiple agents or execution stages need to be coordinated.
Use Agent Groups when multi-agent work should be represented as explicit tasks.
Use parallel group execution only when tasks can safely run concurrently.
Use task dependencies when one task requires the result of another.
Keep external integrations behind connections or tools.
Use MCP when an external MCP service provides capabilities that should be exposed to an agent.

BindAI keeps the primary execution interface simple while allowing applications to compose tools, memory, knowledge, retrieval, middleware, workflows, and multi-agent execution around the same agent abstraction.

​Execution

​Running an Agent

​Execution Result

​Structured Output

​Tool Execution

​Advanced Tool Execution

​Multiple Tool Calls

​Tool Execution Failures

​Tool Iterations

​Memory

​Conversation Context

​Knowledge

​Retrievers

​Retrieval-Augmented Generation

​Middleware

​Execution Context

​Streaming

​Chat Execution

​Events

​Hooks and Callbacks

​Execution Configuration

​Execution and Projects

​Execution and Workflows

​Execution and Multi-Agent Systems

​Execution and External Tools

​Execution and MCP

​Error Handling

​Execution Boundaries

​A Complete Execution Example

​Execution Best Practices