Minimal agent

What it does

This is the smallest agent worth running: a single Agent with one tool registered via @agent.tool, called synchronously with agent.run. The model decides on its own when to invoke the tool, reads the result, and folds it into a natural-language answer.

It shows two core concepts working together: an agent as the configured runtime, and a tool as a typed Python function the model can call. The tool schema is derived automatically from your type hints and docstring — there is no separate schema to maintain.

The full agent

minimal.py

from agentroute import Agent
 
agent = Agent(
    name="assistant",
    model="claude-sonnet-4",
    instructions="You are a helpful assistant. Use tools when they help.",
)
 
 
@agent.tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    # A real implementation would call a weather API here.
    return f"It's 21°C and sunny in {city}."
 
 
if __name__ == "__main__":
    result = agent.run("What's the weather in Lisbon? Pack accordingly.")
    print(result)

That is the entire program. Agent(...) configures the agent, @agent.tool registers the function (its name, description, and parameters are inferred from the signature and docstring), and agent.run(...) executes one turn of the agent loop and returns a Result.

Tip

Printing a Result prints its output text — str(result) is the model's final answer. The same object also carries result.usage, result.messages, and result.output. See results for the full surface.

Run it

Set your key once, then run the file. A single OpenRouter key (AGENTROUTE_API_KEY or OPENROUTER_API_KEY) works for every model string.

export AGENTROUTE_API_KEY="sk-or-..."
python minimal.py

You'll want a light jacket for the evening, but Lisbon is 21°C and sunny right
now — sunglasses and short sleeves for the day.

The model called get_weather("Lisbon") behind the scenes, then used the returned string to write its answer. You did not call the tool yourself — the agent loop did, because the prompt made it useful.

How it fits together

Configure the agent

Agent(name=..., model=..., instructions=...) builds the agent. name is required; model accepts a bare name like "claude-sonnet-4" (resolved to a provider for you) and instructions becomes the system prompt.

@agent.tool turns a plain function into a callable the model can invoke. Annotate every parameter — the JSON schema sent to the model is built from those hints, and the docstring becomes the tool description.

Run

agent.run(prompt) runs the loop synchronously: the model may call your tool, read the result, and respond. Use await agent.arun(prompt) from async code instead.

Concepts used

Agents

Configuring an Agent and running it with run / arun.

Tools

Writing typed functions and registering them with @agent.tool.

Results

Reading output, usage, and messages off the returned Result.

Models

How model strings resolve to providers and API keys.

Reference: Agent, tool, Result. Browse more in the examples index.