Skip to content

Getting Started

This guide walks you through installing Stirrup and creating your first agent.

Prerequisites

  • Python 3.12 or higher
  • An API key from your LLM provider (OpenRouter, Anthropic, OpenAI, etc.)

Installation

Install the core framework:

pip install stirrup      # or: uv add stirrup

Or with all optional components:

pip install stirrup[all]  # or: uv add stirrup[all]

Optional Extras

Extra Description
litellm Multi-provider support via LiteLLM (Anthropic, Google, etc.)
docker Docker-based code execution
e2b E2B cloud sandboxes
mcp MCP server support
all All optional components

Your First Agent

Create a simple agent that can search the web and execute code:

import asyncio

from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient


async def main() -> None:
    """Run an agent that searches the web and creates a chart."""

    # Create client using ChatCompletionsClient
    # Automatically uses OPENROUTER_API_KEY environment variable
    client = ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-sonnet-4.5",
    )

    # As no tools are provided, the agent will use the default tools, which consist of:
    # - Web tools (web search and web fetching, note web search requires BRAVE_API_KEY)
    # - Local code execution tool (to execute shell commands)
    agent = Agent(client=client, name="agent", max_turns=15)

    # Run with session context - handles tool lifecycle, logging and file outputs
    async with agent.session(output_dir="output/getting_started_example") as session:
        _finish_params, _history, _metadata = await session.run(
            """
        What is the population of the US over the last 3 years? Search the web to
        find out and create a chart using matplotlib showing the population per year.
        """
        )


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

Environment Variables

This example uses OpenRouter. Set OPENROUTER_API_KEY in your environment before running.

Web search requires a BRAVE_API_KEY. The agent will still work without it, but web search will be unavailable.

Tools

By default, agents include code execution and web tools:

Tool Description
code_exec Execute shell commands in an isolated temp directory
web_fetch Fetch and parse web pages
web_search Search the web (requires BRAVE_API_KEY)

Extend with additional tools:

import asyncio

from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import CALCULATOR_TOOL, DEFAULT_TOOLS

# Create client for OpenRouter
client = ChatCompletionsClient(
    base_url="https://openrouter.ai/api/v1",
    model="anthropic/claude-sonnet-4.5",
)

# Create agent with default tools + calculator tool
agent = Agent(
    client=client,
    name="web_calculator_agent",
    tools=[*DEFAULT_TOOLS, CALCULATOR_TOOL],
)

→ See Tools for full documentation on DEFAULT_TOOLS, custom tools, sub-agents, and tool providers.

Choosing a Client

stirrup ships with support for OpenAI-Compatible APIs and LiteLLM, with the open to build your own client.

OpenAI-Compatible APIs

Use ChatCompletionsClient to use OpenAI models or OpenAI-compatible APIs:

    # Create client using Deepseek's OpenAI-compatible endpoint
    client = ChatCompletionsClient(
        base_url="https://api.deepseek.com",
        model="deepseek-chat",  # or "deepseek-reasoner" for R1
        api_key=os.environ["DEEPSEEK_API_KEY"],
    )

    agent = Agent(client=client, name="deepseek_agent")

→ See Client for parameter tables and creating custom clients.

Understanding the Output

The run() method returns three values:

finish_params, history, metadata = await session.run("Your task")
  • finish_params: Agent's final response (reason, paths)
  • history: Conversation message history
  • metadata: Aggregated tool metadata and token usage

→ See Understanding Agent Output for details.

Uploading Input Files

Provide files to the agent's execution environment:

async with agent.session(
    input_files=["data.csv", "config.json"],
    output_dir="./output",
) as session:
    await session.run("Analyze the data")

Supports single files, lists, directories, and glob patterns ("data/*.csv").

→ See Passing Input Files for details.

Saving Output Files

Save files created by the agent by providing an output directory through the session output_dir argument:

async with agent.session(output_dir="./results") as session:
    finish_params, _, _ = await session.run("Create a chart")
    # Files in finish_params.paths are saved to ./results/

→ See Receiving Output Files for details.

Next Steps