Agents

Agents are the core building block of BindAI. An agent combines a language model, instructions, tools, memory, and optional knowledge into a reusable AI component capable of completing tasks autonomously. Every interaction in BindAI starts with an agent.

What is an Agent?

An agent is more than a language model. It consists of:

a model provider
system instructions
conversation history
tools
memory
optional knowledge
execution pipeline

Together these components allow the agent to reason, call tools, remember previous interactions, and produce responses.

Agent Architecture

User
   │
   ▼
Agent
   │
   ├── Instructions
   ├── Model Provider
   ├── Conversation
   ├── Tools
   ├── Memory
   ├── Knowledge
   └── Execution Engine
           │
           ▼
      Model Response

The execution engine coordinates every step of the interaction.

Creating an Agent

The simplest agent can be created directly in Python.

from bindai_agent import Agent
from bindai_openai import OpenAIProvider

agent = Agent(
    name="assistant",
    provider=OpenAIProvider.from_env(),
    instructions="You are a helpful assistant."
)

The agent can then answer questions.

response = agent.chat(
    "Hello!"
)

print(response.output)

YAML Configuration

BindAI also supports creating agents from YAML.

name: assistant

model: openai:gpt-4.1-mini

instructions: |
  You are a helpful assistant.

Loading the agent:

from bindai_agent import Agent

agent = Agent.from_yaml(
    "assistant.yaml"
)

YAML configuration keeps prompts separate from application code and makes agents easier to maintain.

Agent Lifecycle

Every execution follows the same pipeline.

User Input
      │
      ▼
Initialization
      │
      ▼
Knowledge Retrieval
      │
      ▼
Memory Loading
      │
      ▼
Model Generation
      │
      ▼
Tool Execution
      │
      ▼
Response

This pipeline is handled automatically by the BindAI execution engine.

Instructions

Instructions define the behavior of an agent. Example:

You are an experienced software architect.

Always explain your reasoning clearly.

Prefer concise answers.

Instructions are inserted as the system prompt before the conversation begins.

Conversation

Every agent maintains its own conversation.

agent.chat("Hello")

agent.chat("Who are you?")

The second request automatically includes the previous conversation. Conversation history is stored separately from memory.

Memory

Memory allows an agent to remember information across multiple sessions. Example:

agent.use_memory(memory)

Memory providers include:

In-memory
Redis
PostgreSQL
Custom providers

Memory is optional.

Knowledge

Knowledge provides external information during execution. Examples include:

documentation
PDFs
Markdown
databases
vector stores

Knowledge retrieval occurs before the model generates its response.

Tools

Agents can execute Python functions during reasoning.

agent.tool(
    calculator
)

When the language model determines that a tool is needed, BindAI automatically executes it and continues the conversation. One agent can use multiple tools.

Providers

The model provider determines which LLM executes the request. Supported providers include:

OpenAI
Anthropic
Google Gemini
Ollama
Local models

Changing providers does not require changing application logic.

Middleware

Middleware executes before and after agent execution. Example use cases include:

authentication
logging
telemetry
monitoring
request modification

Middleware affects every execution performed by the agent.

Events

Agents publish execution events. Examples include:

execution started
model request
model response
tool executed
execution finished

Events make it easy to integrate monitoring and analytics.

Hooks

Hooks execute custom Python code after important stages. Example:

agent.hook(my_hook)

Hooks can inspect:

execution context
variables
result
conversation

Streaming

Agents support streaming responses.

for chunk in agent.stream(
    "Write a poem."
):
    print(chunk.delta)

Streaming returns tokens as they are generated instead of waiting for the complete response.

Structured Output

Agents can return strongly typed objects.

class Person:

    name: str

    age: int

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

The provider returns JSON which BindAI converts into the requested object.

Using Agents Inside Workflows

Agents integrate directly with workflows.

builder.agent(
    agent,
    input_variable="question",
    output_variable="answer",
)

Workflow variables become the agent input, and the result is stored back into the workflow context.

Best Practices

Give each agent one clear responsibility.
Keep instructions concise.
Reuse tools instead of duplicating logic.
Store prompts in YAML.
Use memory only when persistence is required.
Keep knowledge sources focused on a specific domain.
Prefer workflows to coordinate multiple agents.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

API Reference

02.1 agents

Agents

What is an Agent?

Agent Architecture

Creating an Agent

YAML Configuration

Agent Lifecycle

Instructions

Conversation

Memory

Knowledge

Tools

Providers

Middleware

Events

Hooks

Streaming

Structured Output

Using Agents Inside Workflows

Best Practices

​Agents

​What is an Agent?

​Agent Architecture

​Creating an Agent

​YAML Configuration

​Agent Lifecycle

​Instructions

​Conversation

​Memory

​Knowledge

​Tools

​Providers

​Middleware

​Events

​Hooks

​Streaming

​Structured Output

​Using Agents Inside Workflows

​Best Practices

Agents

What is an Agent?

Agent Architecture

Creating an Agent

YAML Configuration

Agent Lifecycle

Instructions

Conversation

Memory

Knowledge

Tools

Providers

Middleware

Events

Hooks

Streaming

Structured Output

Using Agents Inside Workflows

Best Practices