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:

User

↓

Agent

↓

Language Model

↓

Response

---

Creating an Agent

Agents can be created programmatically or loaded from configuration files.

Example:

agent = Agent(...)

or

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

---

Public Methods

run()

Executes the agent and returns the complete response.

Example:

result = agent.run(
    "Hello",
)

Returns

An AgentResult containing:

• success state
• output
• error (if any)

---

stream()

Streams the generated response incrementally.

Example:

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:

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:

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.

Agent

↓

Tool

↓

Result

↓

Continue

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

---

Memory

Agents may use conversation memory.

Conversation

↓

Memory

↓

Agent

Memory enables context-aware conversations across multiple interactions.

---

Knowledge

Agents may retrieve external knowledge before generating a response.

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.