Agent API Reference

The Agent class is the primary runtime component of BindAI. An agent combines a model provider with instructions, tools, memory, Knowledge, and execution behavior to process requests. This page documents the current public Agent API and the main components that interact with it.

Overview

An Agent can:

Receive user input.
Execute requests through a configured model provider.
Use instructions and runtime context.
Invoke registered tools.
Access Memory.
Retrieve Knowledge.
Return an AgentResult.
Stream generated output.
Participate in workflows.
Participate in multi-agent execution.

Conceptually:

User
  |
  v
Agent
  |
  +---- Model Provider
  +---- Tools
  +---- Memory
  +---- Knowledge
  |
  v
AgentResult

Creating an Agent

The recommended programmatic construction API is Agent.builder().

from bindai_core import Agent

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

The builder can be used to configure the main components of an agent before creating the runtime instance. Common configuration includes:

Name
Description
Instructions
Model provider
Tools
Memory
Knowledge
Retriever
Middleware
Hooks
Callbacks
Execution configuration

The exact builder methods available depend on the installed BindAI version.

run()

run() executes the agent for a user message and returns an AgentResult.

result = agent.run("Hello")

The result can then be inspected:

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

run() is the primary API for complete, non-streaming agent execution.

AgentResult

Successful execution returns an AgentResult. The primary properties are:

Property	Description
`success`	Indicates whether execution succeeded.
`output`	The final agent output.
`error`	Error information when execution fails.

For example:

result = agent.run("Explain artificial intelligence.")

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

Applications should inspect success before relying on the output.

stream()

stream() provides incremental agent output.

for chunk in agent.stream("Explain artificial intelligence."):
    print(chunk)

Streaming is useful for applications where output should be displayed while generation is taking place. Typical use cases include:

Chat interfaces
Interactive assistants
Long responses
User-facing applications

The streaming interface differs from run() because it exposes incremental output rather than a single completed AgentResult.

Structured Output

Agents can be configured to produce structured results using a supported output type. For example, a Pydantic model can define the expected structure:

from pydantic import BaseModel
from bindai_core import Agent


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


agent = (
    Agent.builder()
    .name("person-extractor")
    .instructions("Extract the person's name and age.")
    .provider("openai:gpt-4.1-mini")
    .build()
)

result = agent.run(
    "Alice is 30 years old.",
    output=Person,
)

The exact structured-output behavior depends on the configured model provider.

Providers

An Agent uses a configured model provider to generate responses. BindAI supports provider/model identifiers such as:

openai:gpt-4.1-mini
anthropic:claude-sonnet-4
google:gemini-2.5-flash
groq:llama-3.3-70b-versatile
ollama:llama3
openrouter:openai/gpt-4.1-mini

Provider configuration is separate from the agent’s higher-level behavior. This allows the same agent architecture to work with different supported providers.

Instructions

Agent instructions define the behavior the model should follow. For example:

agent = (
    Agent.builder()
    .instructions("You are a concise technical assistant. Explain concepts clearly and accurately.")
    .provider("openai:gpt-4.1-mini")
    .build()
)

Instructions can be combined with runtime input and other execution context when the agent builds its model request.

Runtime Input

The user message is supplied when the agent executes.

result = agent.run("What is retrieval-augmented generation?")

The runtime input is distinct from the agent’s persistent instructions. This allows the same agent instance to process multiple requests.

Tools

Agents can use tools registered with the agent.

def get_weather(city: str) -> str:
    return f"Weather information for {city}"


agent = (
    Agent.builder()
    .instructions("Help users with weather questions.")
    .provider("openai:gpt-4.1-mini")
    .tool(get_weather)
    .build()
)

Tools allow an agent to perform operations beyond model generation. Typical tool use cases include:

External APIs
Search
Database operations
Calculations
File operations
Business operations
External service integrations

Tool execution is handled separately from the model provider.

Memory

An agent can be configured with a Memory provider. Conceptually:

Agent
  |
  v
Memory
  |
  v
Persistent or Temporary State

For example:

from bindai_core import Agent
from bindai_memory import SQLiteMemoryProvider

memory = SQLiteMemoryProvider("memory.db")

agent = (
    Agent.builder()
    .instructions("You are a conversational assistant.")
    .provider("openai:gpt-4.1-mini")
    .memory(memory)
    .build()
)

Memory provides application-level storage and retrieval capabilities. It should not be confused with the current execution context or Knowledge retrieval.

Knowledge

An agent can use Knowledge and retrieval capabilities to ground responses in external information. Conceptually:

Knowledge
   |
   v
Retriever
   |
   v
Agent
   |
   v
Model

Knowledge can provide information from indexed documents and other supported sources. This is useful for:

Documentation assistants
Internal knowledge systems
Retrieval-augmented generation
Domain-specific assistants
Question answering over indexed content

Retriever

A retriever can be supplied to an agent when the application needs explicit retrieval behavior. Retrieval can use capabilities such as:

Vector search
BM25 search
Hybrid search
Metadata filtering
Reranking
Conversational retrieval

The retriever is responsible for finding relevant Knowledge rather than generating the final response.

Middleware

Agents can be configured with middleware to participate in execution processing. Middleware can be used for concerns such as:

Request processing
Logging
Validation
Execution instrumentation
Cross-cutting behavior

Middleware should remain focused on reusable execution concerns rather than application-specific business logic.

Hooks and Callbacks

Agents can expose execution lifecycle hooks and callbacks. These mechanisms can be used for:

Logging
Instrumentation
Monitoring
Custom execution behavior
Integration with external systems

The exact callback signatures and lifecycle events should be taken from the current BindAI implementation rather than assumed from a generic agent framework.

Events

Agent execution can participate in BindAI’s event system. Events provide a way for applications to observe execution activity without placing logging or monitoring logic directly into every agent operation. Events can be useful for:

Debugging
Execution tracing
Monitoring
External notifications
Workflow integration

Delegation and Multi-Agent Execution

Agents can participate in multi-agent architectures. An agent may delegate work to another agent or participate in a configured team or role chain. Conceptually:

Agent A
   |
   v
Agent B
   |
   v
Specialist

Multi-agent execution can combine:

Delegation
Teams
Specialist agents
Role chains
Knowledge retrieval

The exact orchestration API belongs to the multi-agent and workflow layers.

Workflow Integration

Agents can be used as operations within workflows. Conceptually:

Workflow
   |
   v
Agent
   |
   v
AgentResult

A workflow can use the result of one agent execution as input to later operations. This allows agents to participate in larger processes involving:

Conditions
Loops
Parallel execution
Retries
Timeouts
Human tasks
External integrations

Error Handling

Agent execution can fail for several reasons. Examples include:

Provider failures
Invalid configuration
Tool failures
Knowledge or retrieval failures
Memory failures
Model errors
Execution errors

The result should be inspected after execution:

result = agent.run("Hello")

if not result.success:
    print(result.error)

Applications should not assume that every execution produces valid output.

Exceptions vs AgentResult

An AgentResult represents the normal execution result. Some failures may instead occur as exceptions during configuration, setup, or execution. Applications should therefore distinguish between:

Successful execution
        |
        v
AgentResult(success=True)


Handled execution failure
        |
        v
AgentResult(success=False)


Unexpected/programming/configuration failure
        |
        v
Exception

The appropriate handling depends on where the failure occurs.

Streaming vs run()

`run()`	`stream()`
Complete execution	Incremental output
Returns `AgentResult`	Produces streamed chunks
Convenient for programmatic processing	Useful for interactive interfaces
Output available after execution	Output available during generation

Use run() when the application needs a completed result. Use stream() when incremental output improves the user experience.

Agent State

An Agent instance can hold configured runtime components such as:

Provider configuration
Instructions
Tools
Memory
Knowledge
Retriever
Middleware
Hooks
Callbacks

Application-specific state should generally be stored in the appropriate subsystem rather than embedded as arbitrary mutable agent state. For persistent information, use Memory or another appropriate storage mechanism.

Resource Management

Some agent dependencies may manage external resources. Examples include:

Database connections
Memory providers
Vector stores
External clients

Applications should follow the lifecycle requirements of those dependencies. For example, persistent memory providers may need to be explicitly closed when the application shuts down.

Security

Agents may have access to tools, external services, Knowledge, and Memory. Therefore:

Give agents only the tools they require.
Limit external-service permissions.
Keep credentials outside prompts.
Validate tool inputs.
Restrict state-changing operations.
Protect sensitive Knowledge.
Avoid exposing secrets through model output.
Apply appropriate access controls around persistent storage.

The agent itself should not be treated as a security boundary.

Testing

Agents should be tested at multiple levels. Useful tests include:

Agent construction
Provider configuration
Instruction behavior
Tool execution
Memory integration
Knowledge retrieval
Structured output
Error handling
Streaming
Multi-agent behavior
Workflow integration

External providers should generally be mocked or isolated during unit tests. Integration tests can validate real provider behavior separately.

API Accuracy

The current public Agent API is centered around programmatic construction and execution. This documentation intentionally does not assume APIs such as:

Agent.from_yaml(...)
Agent.load(...)
Agent.from_config(...)
agent.configure(...)
agent.authenticate(...)

unless they are explicitly implemented by the installed BindAI version. Likewise, deployment systems, project registries, workflow orchestration, and provider-specific features should not be inferred from the Agent API alone.

The Agent API works closely with:

AgentResult
Providers
Tools
Memory
Knowledge
Retrievers
Workflows
Connections
Multi-agent execution

These components can be combined to build larger BindAI applications.

Summary

The Agent class is a central runtime component of BindAI. The primary lifecycle is:

Build Agent
    |
    v
Configure Provider / Instructions / Tools
    |
    +---- Memory
    +---- Knowledge
    +---- Retriever
    |
    v
Run or Stream
    |
    v
AgentResult / Streamed Output

The current API emphasizes composable programmatic agent construction through Agent.builder(), execution through run() and stream(), and integration with tools, Memory, Knowledge, workflows, and multi-agent systems. Higher-level deployment, hosting, and application-management concerns belong outside the core Agent API unless explicitly implemented by the corresponding BindAI subsystem.

​Agent API Reference

​Overview

​Creating an Agent

​run()

​AgentResult

​stream()

​Structured Output

​Providers

​Instructions

​Runtime Input

​Tools

​Memory

​Knowledge

​Retriever

​Middleware

​Hooks and Callbacks

​Events

​Delegation and Multi-Agent Execution

​Workflow Integration

​Error Handling

​Exceptions vs AgentResult

​Streaming vs run()

​Agent State

​Resource Management

​Security

​Testing

​API Accuracy

​Related APIs

​Summary