Quick Start Guide

Installation

Install python-agents using pip:

pip install python-agents

Or using uv:

uv add python-agents

Basic Usage

LLMClient Example

The simplest way to use python-agents is with the LLMClient:

from python_agents.client import LLMClient
import asyncio

async def main():
    client = LLMClient("openai/gpt-4.1-mini")
    response = await client.invoke("What is 1+1?")
    print(response.message.content)

asyncio.run(main())

Tool Calling

Define Python functions and register them as tools:

def calculator(operation: str, a: int, b: int):
    """Perform operation on parameters a and b.

    :param operation: string representing the operation. Supported: '+', '-', '*', '/'.
    :param a: First operand.
    :param b: Second operand.
    :return: result of the operation.
    """
    if operation == "+":
        return a + b
    elif operation == "-":
        return a - b
    elif operation == "*":
        return a * b
    elif operation == "/":
        return a / b
    else:
        return "Wrong operation!"

async def test_tool():
    client = LLMClient("openai/gpt-4.1-mini")
    client.add_tool(calculator)
    response = await client.invoke("What is 7+2 and what is 9*45?")
    print(response.message.content)

ReactAgent Example

Use ReactAgent for multi-step reasoning tasks:

import os
import asyncio
import random

from python_agents.client import LLMClient
from python_agents.agents import ReactAgent
from tavily import TavilyClient
from dotenv import load_dotenv

load_dotenv()

def search_internet(query: str):
    """Search the internet for the given query."""
    tavily_client = TavilyClient(api_key=os.environ.get("TAVILY_API_KEY"))
    response = tavily_client.search(query)
    return response

def get_random_number() -> int:
    """Return a random number between 1 and 100."""
    return random.randint(0, 100)

def calculator(operation: str, a: int, b: int):
    """Perform operation on parameters a and b."""
    if operation == "+":
        return a + b
    elif operation == "-":
        return a - b
    elif operation == "*":
        return a * b
    elif operation == "/":
        return a / b
    else:
        return "Wrong operation!"

async def run_agent():
    client = LLMClient("openai/gpt-4.1-mini")
    client.add_tool(calculator)
    client.add_tool(get_random_number)
    client.add_tool(search_internet)
    agent = ReactAgent(client)

    response = await agent.run(
        "Look up when the iPhone was first released, then find what major world "
        "event happened that same year, then tell me who was the US president during that event.",
        verbose=True
    )
    print(f"Agent final answer: {response}")

if __name__ == "__main__":
    asyncio.run(run_agent())

Key Concepts

Create tools as Python functions with type hints and docstrings
Instantiate an LLMClient with your model name
Register tools using client.add_tool(func)
Create an Agent (ReactAgent) with the client
Run the agent with agent.run() for multi-step tasks
Use async/await - all operations are asynchronous

Next Steps

Explore the API Reference reference for detailed documentation
Check the GitHub repository for more examples
Learn about the REACT pattern and how agents reason step-by-step