> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 02.1 agents

# 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

```text theme={null}
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.

```python theme={null}
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.

```python theme={null}
response = agent.chat(
    "Hello!"
)

print(response.output)
```

***

# YAML Configuration

BindAI also supports creating agents from YAML.

```yaml theme={null}
name: assistant

model: openai:gpt-4.1-mini

instructions: |
  You are a helpful assistant.
```

Loading the agent:

```python theme={null}
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.

```text theme={null}
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:

```text theme={null}
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.

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
agent.hook(my_hook)
```

Hooks can inspect:

* execution context
* variables
* result
* conversation

***

# Streaming

Agents support streaming responses.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.