agent_framework/README.md

Agent Framework

A flexible framework for building AI agents with tool support, MCP integration, and multi-step reasoning.

Structure

agent_framework/
├── __init__.py      # Package exports
├── models.py        # Core data models (Message, ToolCall, Event, ExecutionContext)
├── tools.py         # BaseTool and FunctionTool classes
├── llm.py           # LlmClient and request/response models
├── agent.py         # Agent and AgentResult classes
├── mcp.py           # MCP tool loading utilities
└── utils.py         # Helper functions for tool definitions

Quick Start

from agent_framework import Agent, LlmClient, FunctionTool

# Define a tool
def calculator(expression: str) -> float:
    """Calculate mathematical expressions."""
    return eval(expression)

# Create the agent
agent = Agent(
    model=LlmClient(model="gpt-5-mini"),
    tools=[FunctionTool(calculator)],
    instructions="You are a helpful assistant.",
)

# Run the agent
result = await agent.run("What is 1234 * 5678?")
print(result.output)  # "7006652"

Components

Models (models.py)

• Message: Text messages in conversations
• ToolCall: LLM's request to execute a tool
• ToolResult: Result from tool execution
• Event: Recorded occurrence during agent execution
• ExecutionContext: Central storage for execution state

Tools (tools.py)

• BaseTool: Abstract base class for all tools
• FunctionTool: Wraps Python functions as tools

LLM (llm.py)

• LlmClient: Client for LLM API calls using LiteLLM
• LlmRequest: Request object for LLM calls
• LlmResponse: Response object from LLM calls

Agent (agent.py)

• Agent: Main agent class that orchestrates reasoning and tool execution
• AgentResult: Result of an agent execution

MCP (mcp.py)

• load_mcp_tools(): Load tools from MCP servers

Utils (utils.py)

• function_to_input_schema(): Convert function signature to JSON Schema
• format_tool_definition(): Format tool definition in OpenAI format
• tool: Decorator to convert functions to tools

Usage Examples

Basic Tool Usage

from agent_framework import FunctionTool

def my_function(x: int, y: int) -> int:
    """Add two numbers."""
    return x + y

tool = FunctionTool(my_function)
result = await tool.execute(context, x=5, y=3)  # 8

Using the @tool Decorator

from agent_framework import tool

@tool
def multiply(a: float, b: float) -> float:
    """Multiply two numbers."""
    return a * b

# multiply is now a FunctionTool instance

MCP Tool Integration

from agent_framework import load_mcp_tools
import os

connection = {
    "command": "npx",
    "args": ["-y", "tavily-mcp@latest"],
    "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
}

mcp_tools = await load_mcp_tools(connection)
agent = Agent(
    model=LlmClient(model="gpt-5-mini"),
    tools=mcp_tools,
)

Installation

The framework uses:

• pydantic for data validation
• litellm for LLM API calls
• mcp for MCP server integration

Install dependencies:

pip install pydantic litellm mcp