> ## 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.

# 10.1 agent

# Agent API Reference

The `Agent` class is the primary building block of BindAI.

Agents encapsulate AI behavior by combining a language model, prompts, tools, memory, knowledge, and execution settings into a reusable runtime component.

This page documents the public Agent API.

***

# Overview

An Agent is responsible for:

* receiving user input
* building prompts
* invoking language models
* calling tools
* accessing memory
* retrieving knowledge
* returning structured results

Conceptually:

```text id="api-agent-1" theme={null}
User

↓

Agent

↓

Language Model

↓

Response
```

***

# Creating an Agent

Agents can be created programmatically or loaded from configuration files.

Example:

```python id="api-agent-2" theme={null}
agent = Agent(...)
```

or

```python id="api-agent-3" theme={null}
agent = Agent.from_yaml(
    "agent.yaml",
)
```

***

# Public Methods

## run()

Executes the agent and returns the complete response.

Example:

```python id="api-agent-4" theme={null}
result = agent.run(
    "Hello",
)
```

### Returns

An `AgentResult` containing:

* success state
* output
* error (if any)

***

## stream()

Streams the generated response incrementally.

Example:

```python id="api-agent-5" theme={null}
for chunk in agent.stream(
    "Explain AI",
):
    print(chunk)
```

Streaming is recommended for chat interfaces.

***

## from\_yaml()

Creates an agent from a YAML configuration file.

Example:

```python id="api-agent-6" theme={null}
agent = Agent.from_yaml(
    "assistant.yaml",
)
```

This is the recommended approach for production applications.

***

# Configuration

Agents typically contain:

* name
* description
* provider
* model
* system prompt
* user prompt
* tools
* memory
* knowledge
* execution options

These values may be configured programmatically or through YAML.

***

# Language Model

Every agent uses a language model.

Conceptually:

```text id="api-agent-7" theme={null}
Agent

↓

Provider

↓

Model
```

Supported providers depend on the installed BindAI provider packages.

***

# Prompts

Agents support multiple prompt types.

Examples include:

* system prompt
* developer prompt
* user prompt

These prompts are combined before model execution.

***

# Tools

Agents may invoke registered tools during reasoning.

```text id="api-agent-8" theme={null}
Agent

↓

Tool

↓

Result

↓

Continue
```

Tools extend the capabilities of language models by allowing interaction with external systems.

***

# Memory

Agents may use conversation memory.

```text id="api-agent-9" theme={null}
Conversation

↓

Memory

↓

Agent
```

Memory enables context-aware conversations across multiple interactions.

***

# Knowledge

Agents may retrieve external knowledge before generating a response.

```text id="api-agent-10" theme={null}
Knowledge Base

↓

Retriever

↓

Agent
```

Knowledge retrieval allows responses to be grounded in project-specific information.

***

# Results

Agent execution returns an `AgentResult`.

Typical properties include:

| Property | Description                                        |
| -------- | -------------------------------------------------- |
| success  | Indicates whether execution completed successfully |
| output   | Final response generated by the agent              |
| error    | Execution error, if one occurred                   |

***

# Error Handling

Execution errors are captured inside the result object.

Typical errors include:

* provider failures
* invalid configuration
* unavailable tools
* timeout
* model errors

Applications should always inspect the result before using the output.

***

# Streaming vs Run

| run()                              | stream()                     |
| ---------------------------------- | ---------------------------- |
| Returns complete result            | Returns incremental output   |
| Simpler API                        | Better user experience       |
| Suitable for background processing | Suitable for chat interfaces |

Choose the method that best fits your application.

***

# Best Practices

* Load agents from YAML whenever possible.
* Give every agent a clear responsibility.
* Register only the tools required by that agent.
* Keep prompts concise and focused.
* Use memory only when conversational context is needed.
* Attach knowledge sources only when retrieval is required.
* Validate `AgentResult.success` before using the output.

***

# Related APIs

The Agent API works closely with:

* Project
* Workflow
* Tool
* Memory
* Provider

These APIs together form the core BindAI runtime.

***

# Summary

The `Agent` class is the central execution component of BindAI.

It combines prompts, models, tools, memory, and knowledge into a reusable AI service capable of executing requests, streaming responses, participating in workflows, and serving as the foundation for BindAI applications.