first-agent

Building Your First Agent

This guide is the longer cousin of the Quick Start. We'll build a single-tool agent end-to-end, then layer on the things you'll want next: streaming UI, error handling, and a cancel button.

Step 1 — set up the provider and model

The provider is the connection to the LLM API; provider.model("id", ...) binds a model id to that provider and produces the value Agent(model=...) expects.

import os
from cubepi.providers.anthropic import AnthropicProvider

provider = AnthropicProvider(provider_id="anthropic", api_key=os.environ["ANTHROPIC_API_KEY"])
model = provider.model(
    "claude-sonnet-4-6",
    max_tokens=4096,         # response cap
    context_window=200_000,  # hard model limit; defaults are usually fine
    temperature=0.7,
)

provider_id lives on the provider constructor and is propagated into the bound model automatically — used by the framework to gate reasoning fields and tag responses. Building a Model by hand and passing both provider= and model= to Agent is the 0.6 idiom and no longer works in 0.7.

Step 2 — declare a tool

A tool is an async function decorated with @tool:

from cubepi import tool


@tool
async def get_weather(city: str) -> str:
    "Get current weather for a city. Returns a short text summary."
    # do real work here — call an HTTP API, query a DB, etc.
    return f"72°F and sunny in {city}"

A few details:

• The input schema is generated from the typed parameters and sent to the model; the docstring becomes the tool description. Pydantic Field(...) defaults and metadata are honoured.
• Return a str (wrapped as text), a Content, a list of content, or a full AgentToolResult when you need details/is_error.
• Need cancellation or progress streaming? Declare signal (an asyncio.Event set when the user cancels) and/or on_update(partial) in the signature and CubePi injects them — see Tool Use.
• For a shared params model or dynamic construction, the longhand AgentTool(...) is equivalent — see Tool Use.