Basic Examples

Small, runnable snippets covering the everyday building blocks. Each needs an OPENAI_API_KEY in your environment (or swap in another provider). Runnable versions live in the examples/ directory of the repository.

Minimal agent

The simplest agent: a model plus instructions.

from buddy import Agent
from buddy.models.openai import OpenAIChat

agent = Agent(
    name="assistant",
    model=OpenAIChat(id="gpt-4o-mini"),
    instructions="You are a helpful assistant. Be concise.",
    markdown=True,
)

agent.print_response("What is the capital of France?")

What to expect: the answer is printed to the console in a formatted panel. To get the value programmatically, use agent.run(...).content instead.

Agent with tools

Attach built-in tools so the model can search the web and run Python.

from buddy import Agent
from buddy.models.openai import OpenAIChat
from buddy.tools.tavily import TavilyTools
from buddy.tools.python import PythonTools

agent = Agent(
    name="research_agent",
    model=OpenAIChat(id="gpt-4o"),
    tools=[TavilyTools(), PythonTools()],
    instructions=[
        "You are a research assistant.",
        "Use web search for current information.",
        "Run Python to verify calculations.",
    ],
    show_tool_calls=True,
    markdown=True,
)

agent.print_response("What is the price of Bitcoin? How many can I buy with $10,000?")

Tool dependencies

TavilyTools needs pip install tavily-python and a TAVILY_API_KEY. With show_tool_calls=True, each tool invocation is shown in the output.

Agent with memory

Persist user memories across turns with a SQLite-backed Memory.

from buddy import Agent
from buddy.models.openai import OpenAIChat
from buddy.memory.v2.memory import Memory
from buddy.memory.v2.db.sqlite import SqliteMemoryDb

agent = Agent(
    name="memory_agent",
    model=OpenAIChat(id="gpt-4o-mini"),
    memory=Memory(
        model=OpenAIChat(id="gpt-4o-mini"),
        db=SqliteMemoryDb(table_name="user_memories", db_file="tmp/memory.db"),
    ),
    enable_user_memories=True,
    instructions="You are a personal assistant. Reference past conversations.",
    markdown=True,
)

agent.print_response("My name is Alice and I love hiking.", user_id="alice")
agent.print_response("What do you know about me?", user_id="alice")

Memory.db expects a MemoryDb

Pass a memory database such as SqliteMemoryDb (from buddy.memory.v2.db.sqlite) to Memory(db=...). A session Storage backend (buddy.storage.sqlite.SqliteStorage) is a different object — set it via the agent's storage= parameter to persist whole sessions.

What to expect: on the second turn the agent recalls Alice's name and interests from the stored memories.

Streaming

Stream tokens as they are generated by passing stream=True to run(), which returns an iterator of events.

from buddy import Agent
from buddy.models.openai import OpenAIChat

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))

for event in agent.run("Explain how neural networks learn.", stream=True):
    if event.content:
        print(event.content, end="", flush=True)
print()

No run_stream()

Streaming is done with run(message, stream=True) — there is no separate run_stream method. Each yielded item is a RunResponseEvent; check event.content for text deltas.

Structured output

Bind a Pydantic model with response_model to get typed results.

from pydantic import BaseModel
from buddy import Agent
from buddy.models.openai import OpenAIChat

class Movie(BaseModel):
    title: str
    year: int
    director: str

agent = Agent(model=OpenAIChat(id="gpt-4o"), response_model=Movie)

result = agent.run("Give me details about the movie Inception.")
movie = result.content  # a Movie instance
print(movie.title, movie.year, movie.director)

What to expect: result.content is a validated Movie instance, not a string — ready to use directly in your code.