Version: 1.0.0 Last Updated: 2026-05-14 Status: Active

Agent Framework Documentation¶

This directory contains documentation for all 4 agent framework implementations in src/agent/.

Overview¶

The agent frameworks provide different approaches to building AI agents, supporting multiple underlying technologies including OpenAI Agents SDK, Pydantic-AI, and SMOL Agents.

Agent Implementations¶

Agent	Version	Description	Framework
base	0.1.1	Abstract base for agents	Common utilities
openai_agent	0.1.1	OpenAI Agents SDK	openai-agents 0.2.2
pydantic_agent	0.1.1	Pydantic-AI with MCP	pydantic-ai ^0.4.6
smol_agent	0.1.1	SMOL Agents with LiteLLM	smolagents ^1.20.0

Architecture¶

┌─────────────────────────────────────────┐
│           bast-agent-base               │
│     (Common patterns, utilities)        │
└─────────────────────────────────────────┘
         │           │           │
         ▼           ▼           ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│   openai    │ │  pydantic   │ │    smol     │
│   agent     │ │   agent     │ │   agent     │
└─────────────┘ └─────────────┘ └─────────────┘
         │           │           │
         ▼           ▼           ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ openai-     │ │ pydantic-ai │ │ smolagents  │
│ agents SDK  │ │ + MCP       │ │ + litellm   │
└─────────────┘ └─────────────┘ └─────────────┘

Agent Base¶

The bast-agent-base provides:

Abstract base class for agent implementations
Common configuration management
Shared utilities and patterns
Integration with Bast AI config system

Planned Framework Support¶

Framework	Status	Notes
OpenAI Agent SDK	Active	Version 0.2.2
Pydantic-AI	Planned	Requires Python 3.11+
Crew AI	Planned	Future implementation
SMOL Agent	Active	With MCP + LiteLLM
ACP-SDK	Planned	Future implementation

OpenAI Agent¶

Implementation using the official OpenAI Agents SDK.

Features¶

Official OpenAI agent framework
Tool/function calling support
Conversation history management
Streaming responses

Usage¶

from bast_openai_agent import OpenAIAgent

agent = OpenAIAgent(catname="mycat")
response = await agent.run(
    message="Analyze this data",
    tools=["data_lookup", "summarize"],
    context={"user_id": "123"}
)

Pydantic Agent¶

Implementation using Pydantic-AI with MCP support.

Features¶

Type-safe agent responses with Pydantic
MCP (Model Context Protocol) integration
Structured output validation
Multi-model support

Requirements¶

Python 3.11+ (pydantic-ai requirement)

Usage¶

from bast_pydantic_agent import PydanticAgent
from pydantic import BaseModel

class Response(BaseModel):
    answer: str
    confidence: float

agent = PydanticAgent(catname="mycat", output_model=Response)
response = await agent.run("What is the capital of France?")
print(response.answer)  # "Paris"
print(response.confidence)  # 0.99

SMOL Agent¶

Implementation using SMOL Agents with LiteLLM support.

Features¶

Lightweight agent framework
MCP integration
LiteLLM for multi-provider support
Simple, minimal interface

Usage¶

from bast_smol_agent import SmolAgent

agent = SmolAgent(catname="mycat")
response = await agent.run(
    message="Search for recent news about AI",
    model="gpt-4o"  # or any LiteLLM supported model
)

Testing¶

Integration Tests¶

Each agent has integration tests in integration/:

Agent	Integration Test
base	`integration_agent.py`
openai_agent	`integration_agent.py`
pydantic_agent	`integration_agent.py`
smol_agent	`integration_agent.py`

Running Tests¶

# Test specific agent
pants test src/agent/openai_agent:: -- -s --no-header

# Run integration test
pants run src/agent/openai_agent/integration/integration_agent.py

Choosing an Agent Framework¶

Use Case	Recommended Agent	Reason
OpenAI-focused apps	openai_agent	Native SDK support
Type-safe responses	pydantic_agent	Pydantic validation
Multi-provider LLMs	smol_agent	LiteLLM flexibility
MCP integrations	pydantic_agent, smol_agent	Built-in MCP support
Simple prototyping	smol_agent	Minimal setup

Common Patterns¶

Agent Configuration¶

# resources/config/{catname}.yaml
agent:
  type: openai  # or pydantic, smol
  model: gpt-4o
  temperature: 0.7
  max_tokens: 1000
  tools:
    - knowledge_search
    - web_search
    - calculator

Tool Registration¶

from bast_agent_base import AgentBase, tool

class MyAgent(AgentBase):
    @tool
    def search_knowledge(self, query: str) -> list[dict]:
        """Search the knowledge base."""
        return self.kb.search(query)

    @tool
    def calculate(self, expression: str) -> float:
        """Evaluate a mathematical expression."""
        return eval(expression)

Conversation History¶

agent = OpenAIAgent(catname="mycat")

# Maintain conversation
history = []
while True:
    user_input = input("You: ")
    response = await agent.run(user_input, history=history)
    history.append({"role": "user", "content": user_input})
    history.append({"role": "assistant", "content": response})
    print(f"Agent: {response}")

Issues & Improvements¶

Current Issues¶

Python version constraints: Pydantic-AI requires Python 3.11+
Limited tool ecosystem: Few pre-built tools available
No agent orchestration: Can't easily compose multiple agents

Suggested Improvements¶

Unified tool interface: Standard tool definition across all agents
Agent composition: Support for multi-agent workflows
Memory systems: Add long-term memory support
Observability: Add tracing and logging
Caching: Cache LLM responses for repeated queries
Fallback chains: Automatic fallback between agents/models

Dependencies Summary¶

Agent	Key Dependencies
base	bast-ai-config, openai-agents 0.2.2
openai_agent	bast-agent-base, openai-agents 0.2.2
pydantic_agent	bast-agent-base, pydantic-ai ^0.4.6
smol_agent	bast-agent-base, smolagents ^1.20.0

Maintainer¶

Chiranjeevi G (chiranjeevi.g@cygnenoircyber.com) - All agent implementations