Agent Configurations Guide¶

Comprehensive guide for using agent configurations in Bast AI Agno.

Table of Contents¶

Overview
Quick Start
Configuration Schema
Configuration Types
Configuration Utilities
Decision Trees
Best Practices
Examples

Overview¶

Agent configurations are organized by Agno's core concepts and provide pre-configured settings for different use cases. All configurations follow Agno standards and can be customized using utility functions.

Core Components¶

According to Agno's agent overview, agents have these core components:

Model: Controls the flow of execution
Instructions: Program the Agent
Tools: Enable actions and interactions
Memory: Store and recall information
Storage: Session history and state
Knowledge: Domain-specific information (Agentic RAG)
Reasoning: "Think" before responding

Quick Start¶

Basic Usage¶

from bast_ai_agno.dto.agent_configs import basic_agent_config
from bast_ai_agno import AgnoAgentFactory, AgnoMongoDBResources, AgnoModelResources

# Initialize resources
storage_resources = AgnoMongoDBResources("my_cat")
model_resources = AgnoModelResources("my_cat")
factory = AgnoAgentFactory("my_cat")

# Create agent with configuration
agent_storage = storage_resources.get_agent_storage("my_agent")
agent_model = model_resources.get_open_ai_chat("gpt-4o-mini")

agent = factory.create_openai_chat_agent(
    name="my_agent",
    model=agent_model,
    db=agent_storage,
    config_raw=basic_agent_config
)

Using Utilities¶

from bast_ai_agno.dto.agent_configs import basic_agent_config
from bast_ai_agno.dto.agent_tool_utils import add_tools_to_config
from agno.tools.duckduckgo import DuckDuckGoTools

# Add tools to config
config_with_tools = add_tools_to_config(
    basic_agent_config,
    [DuckDuckGoTools(modifier="site:example.com")]
)

Configuration Schema¶

Core Agent Settings¶

Field	Type	Description	Default
`instructions`	`List[str]`	Agent instructions	Required
`description`	`str`	Agent description	`None`
`name`	`str`	Agent name	Auto-generated

Memory Settings¶

Field	Type	Description	Default
`enable_agentic_memory`	`bool`	Enable agentic memory (create/update/delete)	`False`
`enable_user_memories`	`bool`	Enable user memories (create/update only)	`False`
`add_memories_to_context`	`bool`	Add memories to context	`False`

Reference: Agno Memory Documentation

Storage & Sessions Settings¶

Field	Type	Description	Default
`add_history_to_context`	`bool`	Add chat history to context	`False`
`num_history_runs`	`int`	Number of history runs to include	`0`
`cache_session`	`bool`	Cache session state	`False`
`search_session_history`	`bool`	Search across sessions	`False`
`num_history_sessions`	`int`	Number of sessions to search	`0`
`enable_session_summaries`	`bool`	Generate session summaries	`False`
`add_session_summary_to_context`	`bool`	Add session summary to context	`False`

Reference: Agno Storage Documentation

Knowledge (Agentic RAG) Settings¶

Field	Type	Description	Default
`search_knowledge`	`bool`	Enable knowledge search at runtime	`False`
`knowledge_filters`	`List`	Knowledge filters	`None`
`enable_agentic_knowledge_filters`	`bool`	Let agent decide when to filter	`False`

Reference: Agno Knowledge Documentation

Tools Settings¶

Field	Type	Description	Default
`tools`	`List[Tool]`	List of tool instances	`[]`
`tool_call_limit`	`int`	Maximum tool calls per run	`None`
`tool_choice`	`str`	Tool choice strategy ("auto", "required", "none")	`"auto"`

Reference: Agno Tools Documentation

Reasoning Settings¶

Field	Type	Description	Default
`reasoning`	`bool`	Enable reasoning mode	`False`
`reasoning_min_steps`	`int`	Minimum reasoning steps	`1`
`reasoning_max_steps`	`int`	Maximum reasoning steps	`10`

Reference: Agno Reasoning Documentation

Dependencies Settings¶

Field	Type	Description	Default
`dependencies`	`List[Agent]`	List of agent dependencies	`None`
`add_dependencies_to_context`	`bool`	Add dependencies to context	`False`

Reference: Agno Dependencies Documentation

Context Engineering Settings¶

Field	Type	Description	Default
`build_context`	`bool`	Enable context building	`True`
`resolve_in_context`	`bool`	Resolve variables in context	`True`
`add_name_to_context`	`bool`	Add agent name to context	`False`
`add_datetime_to_context`	`bool`	Add current datetime to context	`False`
`add_location_to_context`	`bool`	Add location to context	`False`
`timezone_identifier`	`str`	Timezone for datetime context	`None`

Reference: Agno Context Engineering Documentation

Hooks & Guardrails Settings¶

Field	Type	Description	Default
`pre_hooks`	`List[Callable]`	Functions to run before execution	`None`
`post_hooks`	`List[Callable]`	Functions to run after execution	`None`
`guardrails`	`List[Callable]`	Functions to validate/constrain behavior	`None`

Reference: - Agno Pre-hooks & Post-hooks Documentation - Agno Guardrails Documentation

Configuration Types¶

Core Agent Configurations¶

Located in: core_agent_configs.py

simple_agent - Default agent with basic settings
basic_agent_config - Basic helpful assistant
minimal_agent_config - Minimal configuration
verbose_agent_config - Verbose with detailed explanations
memory_disabled_agent_config - Memory disabled
greeting_agent_config - Friendly greeting assistant (mimics greeting model)
end_conversation_agent_config - Polite conversation ending assistant (mimics end_conversation model)
early_exit_agent_config - Quick early exit decision assistant (mimics early_exit model)

When to use: - Start here for simple agents without special features - greeting_agent_config: When you need agents that respond with friendly greetings - end_conversation_agent_config: When you need agents that provide polite closing messages - early_exit_agent_config: When you need agents that quickly determine if a conversation should exit early

Memory Configurations¶

Located in: memory_configs.py

memory_agent_config - Full memory capabilities enabled

When to use: When you need agents that remember user preferences and past interactions.

Reference: Agno Memory Documentation

Storage & Sessions Configurations¶

Located in: storage_session_configs.py

session_aware_agent_config - Session-aware with history
stateless_agent_config - Stateless, no session caching
session_optimized_agent_config - Optimized for multi-turn conversations
stateful_agent_config - Agentic state enabled

When to use: - session_aware_agent_config: Multi-session conversations - stateless_agent_config: Single-request agents - session_optimized_agent_config: Long conversations - stateful_agent_config: Stateful applications

Reference: Agno Storage Documentation

Knowledge (Agentic RAG) Configurations¶

Located in: knowledge_configs.py

knowledge_agent_config - Medical assistant with knowledge base
rxdemo_agent_config - RX demo with specific formatting

When to use: When you have a knowledge base and want agents to search it at runtime.

Reference: Agno Knowledge Documentation

Tools Configurations¶

Located in: tools_configs.py

tool_enabled_agent_config - Research assistant with web search tools

When to use: When agents need to interact with external systems or APIs.

Reference: Agno Tools Documentation

Reasoning Configurations¶

Located in: reasoning_configs.py

reasoning_agent_config - Standard reasoning (1-10 steps)
deep_reasoning_agent_config - Deep reasoning (3-20 steps)
light_reasoning_agent_config - Light reasoning (1-3 steps)

When to use: - reasoning_agent_config: Complex problems requiring analysis - deep_reasoning_agent_config: Very complex problems - light_reasoning_agent_config: Simple problems needing brief thought

Reference: Agno Reasoning Documentation

Dependencies Configurations¶

Located in: dependencies_configs.py

dependency_enabled_agent_config - Basic dependency support
dependency_heavy_agent_config - Orchestrator for multiple agents

When to use: When agents need to coordinate with other agents.

Reference: Agno Dependencies Documentation

Context Engineering Configurations¶

Located in: context_engineering_configs.py

enhanced_context_agent_config - Enhanced context with name, datetime, location
minimal_context_agent_config - Minimal context
datetime_aware_agent_config - Datetime-aware with timezone
context_rich_agent_config - Rich context with all features

When to use: When you need agents to be aware of temporal, spatial, or identity information.

Reference: Agno Context Engineering Documentation

Hooks & Guardrails Configurations¶

Located in: hooks_guardrails_configs.py

monitored_agent_config - Basic monitoring with hooks
guarded_agent_config - Safety-focused with guardrails
hooked_agent_config - Execution hooks only
full_monitored_agent_config - Full monitoring with telemetry

When to use: - monitored_agent_config: Logging and monitoring needs - guarded_agent_config: Safety-critical applications - hooked_agent_config: Custom execution hooks - full_monitored_agent_config: Production monitoring

Reference: - Agno Pre-hooks & Post-hooks Documentation - Agno Guardrails Documentation

Full-Featured Configurations¶

Located in: full_featured_configs.py

full_featured_agent_config - Comprehensive configuration with all features

When to use: When you need agents with knowledge, tools, memory, and all features enabled.

Output Schemas¶

Located in: dto/output/

EarlyExitDecision - Output schema for early exit decision analysis (used with early_exit_agent_config)

When to use: When you need structured output for early exit decisions. The early_exit_agent_config includes this schema by default.

Schema Structure: - action: "HARD_EXIT" | "SOFT_EXIT" | "KEEP_GOING" - The exit action to take - reason: str - Brief explanation (e.g., "EMPTY_INPUT", "HAS_ENDING_PHRASE", "GREETING_MSG", "NO_EXIT")

Configuration Utilities¶

Tool Utilities¶

Located in: agent_tool_utils.py

add_tools_to_config(config, tools) - Add tools to config
add_output_schema_to_config(config, output_schema) - Add output schema
add_tools_and_schema_to_config(config, tools, output_schema) - Add both
create_tool_agent_config(tools, tool_call_limit, tool_choice) - Create optimized tool agent

Reasoning Utilities¶

Located in: agent_reasoning_utils.py

build_reasoning_config(base_config, min_steps, max_steps) - Add reasoning to config
create_reasoning_agent_config(min_steps, max_steps, enable_memory) - Create reasoning agent

Session Utilities¶

Located in: agent_session_utils.py

build_session_config(base_config, cache, num_sessions, enable_summaries) - Add session management
create_conversational_agent_config(enable_memory, num_history_runs, enable_session_summaries) - Create conversational agent

Dependency Utilities¶

Located in: agent_dependency_utils.py

build_dependency_config(base_config, dependencies, add_to_context) - Add dependencies

Context Utilities¶

Located in: agent_context_utils.py

build_context_enhanced_config(base_config, add_name, add_datetime, add_location, timezone) - Add context engineering

Guardrails Utilities¶

Located in: agent_guardrails_utils.py

build_guarded_config(base_config, guardrails, pre_hooks, post_hooks) - Add guardrails and hooks

Validation Utilities¶

Located in: agent_validation_utils.py

validate_agent_config(config) - Comprehensive validation
validate_reasoning_config(config) - Validate reasoning config

Merge Utilities¶

Located in: agent_merge_utils.py

merge_configs(*configs, strategy) - Merge multiple configs

Preset Utilities¶

Located in: agent_preset_utils.py

create_rag_agent_config(knowledge_base_name, search_knowledge, enable_memory) - Create RAG agent

Decision Trees¶

Which Configuration Should I Use?¶

Start Here
    │
    ├─ Need knowledge base search?
    │   ├─ Yes → Use knowledge_configs.py
    │   │   ├─ Medical domain? → Use rxdemo_agent_config
    │   │   └─ General → Use knowledge_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need external tools?
    │   ├─ Yes → Use tools_configs.py
    │   │   └─ Use tool_enabled_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need reasoning?
    │   ├─ Yes → Use reasoning_configs.py
    │   │   ├─ Complex problems → deep_reasoning_agent_config
    │   │   ├─ Standard problems → reasoning_agent_config
    │   │   └─ Simple problems → light_reasoning_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need memory?
    │   ├─ Yes → Use memory_configs.py
    │   │   └─ Use memory_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need session management?
    │   ├─ Yes → Use storage_session_configs.py
    │   │   ├─ Multi-session → session_aware_agent_config
    │   │   ├─ Long conversations → session_optimized_agent_config
    │   │   ├─ Stateful → stateful_agent_config
    │   │   └─ Stateless → stateless_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need dependencies?
    │   ├─ Yes → Use dependencies_configs.py
    │   │   ├─ Multiple agents → dependency_heavy_agent_config
    │   │   └─ Basic → dependency_enabled_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need context engineering?
    │   ├─ Yes → Use context_engineering_configs.py
    │   │   ├─ All features → context_rich_agent_config
    │   │   ├─ Datetime only → datetime_aware_agent_config
    │   │   └─ Enhanced → enhanced_context_agent_config
    │   │
    │   └─ No → Continue
    │
    ├─ Need hooks/guardrails?
    │   ├─ Yes → Use hooks_guardrails_configs.py
    │   │   ├─ Full monitoring → full_monitored_agent_config
    │   │   ├─ Safety only → guarded_agent_config
    │   │   └─ Basic → monitored_agent_config
    │   │
    │   └─ No → Continue
    │
    └─ Basic agent → Use core_agent_configs.py
        ├─ Minimal → minimal_agent_config
        ├─ Verbose → verbose_agent_config
        └─ Standard → basic_agent_config

When to Use Each Feature¶

Memory¶

✅ User preferences need to be remembered
✅ Personalized responses are important
✅ Long-term context is needed
❌ Stateless single-request agents
❌ No user-specific data

Knowledge (RAG)¶

✅ Domain-specific knowledge base exists
✅ Need to cite sources
✅ Knowledge needs to be searchable at runtime
❌ No knowledge base
❌ Static information in instructions

Tools¶

✅ Need to interact with external APIs
✅ Need web search capabilities
✅ Need to perform actions
❌ No external integrations needed
❌ Only using LLM capabilities

Reasoning¶

✅ Complex problems requiring analysis
✅ Need step-by-step thinking
✅ Quality over speed
❌ Simple queries
❌ Speed is critical

Sessions¶

✅ Multi-turn conversations
✅ Need conversation history
✅ Cross-session context
❌ Single-request agents
❌ No conversation history needed

Best Practices¶

1. Start Simple, Add Complexity¶

# Start with basic config
from bast_ai_agno.dto.agent_configs import basic_agent_config

# Add features as needed
from bast_ai_agno.dto.agent_tool_utils import add_tools_to_config
config = add_tools_to_config(basic_agent_config, tools)

2. Use Presets for Common Patterns¶

# Instead of manually configuring
from bast_ai_agno.dto.agent_preset_utils import create_rag_agent_config
rag_config = create_rag_agent_config(knowledge_base_name="my_kb")

3. Validate Before Use¶

from bast_ai_agno.dto.agent_validation_utils import validate_agent_config

is_valid, errors = validate_agent_config(my_config)
if not is_valid:
    print(f"Errors: {errors}")

4. Merge Configurations Safely¶

from bast_ai_agno.dto.agent_merge_utils import merge_configs

# Merge base with overrides
merged = merge_configs(base_config, override_config, custom_config)

5. Use Specific Imports¶

# Import from specific modules for clarity
from bast_ai_agno.dto.agent_tool_utils import add_tools_to_config
from bast_ai_agno.dto.agent_reasoning_utils import build_reasoning_config

Examples¶

Example 1: Basic Agent¶

from bast_ai_agno.dto.agent_configs import basic_agent_config
from bast_ai_agno import AgnoAgentFactory, AgnoMongoDBResources, AgnoModelResources

factory = AgnoAgentFactory("my_cat")
storage = AgnoMongoDBResources("my_cat").get_agent_storage("basic")
model = AgnoModelResources("my_cat").get_open_ai_chat("gpt-4o-mini")

agent = factory.create_openai_chat_agent(
    name="basic_agent",
    model=model,
    db=storage,
    config_raw=basic_agent_config
)

Example 2: RAG Agent with Knowledge¶

from bast_ai_agno.dto.agent_configs import knowledge_agent_config
from bast_ai_agno import AgnoAgentFactory, AgnoMongoDBResources, AgnoModelResources, AgnoKnowledgeResources

factory = AgnoAgentFactory("my_cat")
storage = AgnoMongoDBResources("my_cat").get_agent_storage("rag")
model = AgnoModelResources("my_cat").get_open_ai_chat("gpt-4o-mini")
knowledge = AgnoKnowledgeResources("my_cat").get_knowledge("my_kb")

agent = factory.create_openai_chat_agent(
    name="rag_agent",
    model=model,
    db=storage,
    knowledge=knowledge,
    config_raw=knowledge_agent_config
)

Example 3: Tool-Enabled Agent¶

from bast_ai_agno.dto.agent_configs import tool_enabled_agent_config
from bast_ai_agno.dto.agent_tool_utils import add_tools_to_config
from agno.tools.duckduckgo import DuckDuckGoTools

# Add tools to config
config = add_tools_to_config(
    tool_enabled_agent_config,
    [DuckDuckGoTools(modifier="site:example.com")]
)

# Create agent with tools
agent = factory.create_openai_chat_agent(
    name="tool_agent",
    model=model,
    db=storage,
    config_raw=config
)

Example 4: Reasoning Agent¶

from bast_ai_agno.dto.agent_configs import basic_agent_config
from bast_ai_agno.dto.agent_reasoning_utils import build_reasoning_config

# Add reasoning to basic config
config = build_reasoning_config(
    basic_agent_config,
    min_steps=2,
    max_steps=15
)

agent = factory.create_openai_chat_agent(
    name="reasoning_agent",
    model=model,
    db=storage,
    config_raw=config
)

Example 5: Full-Featured Agent¶

from bast_ai_agno.dto.agent_configs import full_featured_agent_config
from bast_ai_agno.dto.agent_tool_utils import add_tools_to_config
from bast_ai_agno.dto.agent_validation_utils import validate_agent_config
from agno.tools.duckduckgo import DuckDuckGoTools

# Add tools
config = add_tools_to_config(
    full_featured_agent_config,
    [DuckDuckGoTools(modifier="site:dailymed.nlm.nih.gov")]
)

# Validate
is_valid, errors = validate_agent_config(config)
assert is_valid, f"Config errors: {errors}"

# Create agent
agent = factory.create_openai_chat_agent(
    name="full_agent",
    model=model,
    db=storage,
    knowledge=knowledge,
    config_raw=config
)

Additional Resources¶

Agno Agents Overview
Agno Building Agents
Agno Agent Schema (View the Agent schema link)