Lean Agents

A lightweight Python library for building AI agents with function calling capabilities using OpenAI's API.

Features

• Separation of Concerns - Agent configuration separate from execution logic
• Async/Await Support - Built with asyncio for efficient concurrent operations
• Automatic Schema Generation - Convert Python functions to OpenAI function calling schemas
• Multiple Tools - Support for multiple tools/functions per agent
• Type-Safe - Full type hints support for better IDE integration
• Streaming Responses - Real-time response processing

Installation

# Using uv (recommended)
uv add lean-agents

# Using pip
pip install lean-agents

Quick Start

import asyncio
from lean_agents import Agent, Runner

def add(a: int, b: int) -> int:
    """Add two numbers together and return the result."""
    return int(a) + int(b)

async def main():
    # Create an agent configuration
    agent = Agent(
        instructions="You are a helpful assistant that can handle adding numbers with tool `add`.",
        tools=[add],
        model="gpt-4o-mini"
    )

    # Run the agent (async)
    result = await Runner.run(agent, "What is 123 + 456?")
    print(result.final_output)

asyncio.run(main())

Usage

Defining Tools

Tools are simple Python functions with type hints and docstrings:

def multiply(a: int, b: int) -> int:
    """Multiply two numbers together."""
    return int(a) * int(b)

def get_weather(city: str) -> str:
    """Get the weather for a city."""
    # Your implementation here
    return f"Weather in {city}: Sunny, 25°C"

Creating an Agent

agent = Agent(
    instructions="Your system instructions here",
    tools=[multiply, get_weather],
    model="gpt-4o-mini",  # Optional: defaults to gpt-4o-mini
    api_key="your-api-key"  # Optional: uses OPENAI_API_KEY env var if not provided
)

Running the Agent

Lean Agents provides both async and sync execution methods, similar to OpenAI's agents SDK:

Async execution (recommended):

async def run_example():
    # Execute agent asynchronously
    result = await Runner.run(agent, "What is 15 times 23?")

    # Access the final answer
    print(result.final_output)

    # Access all interaction items (messages, function calls, etc.)
    for item in result.items:
        print(item)

Sync execution:

def run_example_sync():
    # Execute agent synchronously
    result = Runner.run_sync(agent, "What is 15 times 23?")

    # Access the final answer
    print(result.final_output)

Examples

See the examples/ directory for more examples:

• basic_example.py - Simple addition example
• advanced_example.py - Multiple tools and complex interactions

To run an example:

cd examples
python basic_example.py

API Reference

Agent

Agent configuration object that holds instructions, tools, and model settings.

Agent(
    instructions: str,
    tools: list[Callable],
    model: str = "gpt-4o-mini",
    api_key: str | None = None
)

Parameters:

• instructions: System instructions that guide the agent's behavior
• tools: List of callable functions that the agent can use
• model: OpenAI model name (default: "gpt-4o-mini")
• api_key: OpenAI API key (if not provided, uses OPENAI_API_KEY env var)

Runner

Static executor class for running agents. Provides both async and sync methods.

Static Methods:

async run(agent: Agent, input: str) -> RunResult

Run the agent asynchronously with user input.

Parameters:

• agent: The Agent configuration to execute
• input: The user's input text

Returns: RunResult object with:

• final_output: The final text response from the agent
• items: List of all response items (messages, function calls, reasoning, etc.)

Example:

result = await Runner.run(agent, "Your question here")
print(result.final_output)

run_sync(agent: Agent, input: str) -> RunResult

Run the agent synchronously with user input.

Parameters:

• agent: The Agent configuration to execute
• input: The user's input text

Returns: RunResult object (same as async version)

Example:

result = Runner.run_sync(agent, "Your question here")
print(result.final_output)

RunResult

Result object returned by Runner methods.

Attributes:

• final_output (str): The final text response from the agent
• items (list): List of all response items

Requirements

• Python >= 3.10
• openai >= 1.0.0

Development

# Clone the repository
git clone https://github.com/yourusername/lean-agents.git
cd lean-agents

# Install with development dependencies
uv sync --extra dev

# Run tests
pytest

# Format code
black src/

# Lint code
ruff check src/

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.