Context & Usage

Context is the dependency-injection container AgentRoute hands to your tools. It carries the things a tool needs that the model should never see — a database handle, an API client, the current user, the running token tally, a memory handle. Usage is the running tally of tokens, cost, and model calls for a single run; you read it back off result.usage after run().

This page covers both: how to pass deps into a run and read them inside tools, what every Context field holds, and how Usage accumulates.

Dependency injection with deps

Tools often need access to things that live in your application: a database connection, an HTTP client, the authenticated user. Rather than reaching for globals, you pass them once per run as deps, and AgentRoute threads them through to any tool that asks for the Context.

There are two halves to the pattern:

1. Pass your dependencies to run() (or arun()) with the deps= keyword.
2. Declare a parameter annotated Context as the first argument of a tool. AgentRoute injects the live Context there, and your tool reads ctx.deps.

A typed deps dataclass keeps this clean and gives you editor completion inside the tool:

from dataclasses import dataclass
import httpx
 
from agentroute import Agent, Context
 
@dataclass
class Deps:
    http: httpx.Client
    api_key: str
 
agent = Agent(name="weather", model="claude-sonnet-4")
 
@agent.tool
def get_temperature(ctx: Context, city: str) -> str:
    """Return the current temperature for a city in Celsius."""
    resp = ctx.deps.http.get(
        "https://api.weather.example/v1/now",
        params={"city": city, "key": ctx.deps.api_key},
    )
    return f"{resp.json()['temp_c']}C"
 
with httpx.Client() as client:
    deps = Deps(http=client, api_key="wx_live_...")
    result = agent.run("How warm is it in Lisbon?", deps=deps)
    print(result)
    # 24C right now in Lisbon.

The first positional parameter is annotated Context, so AgentRoute injects it automatically. The model never sees ctx — it only sees the city parameter in the tool schema. See Tools for how the rest of the schema is extracted from your type hints and docstring.

The Context fields

Every tool that takes a Context receives the same live instance for the duration of a run. Here is what each field holds.

The full reference, including imports and the dataclass signature, lives on the Context reference page.

Usage: tokens, cost, and model calls

Usage accumulates the cost of a run. AgentRoute updates ctx.usage after each model call, and the final tally is returned as result.usage.

from agentroute import Usage

The dataclass has four fields, all numeric and additive:

Reading result.usage after a run

The most common thing you do with Usage is read it back off the Result to log cost or enforce your own budgets:

from agentroute import Agent
 
agent = Agent(name="summarizer", model="claude-sonnet-4")
result = agent.run("Summarize the last quarter's release notes.")
 
usage = result.usage
print(usage.input_tokens, usage.output_tokens)   # 1840 312
print(f"${usage.total_cost_usd:.4f}")            # $0.0091
print(usage.model_calls)                          # 1

A single-shot answer is one model_calls. An agent that calls tools and loops will report one model call per turn. To cap spend during the run itself rather than after, set max_cost on the agent — see Errors & retries for ErrorBudget.

Accumulating usage with add()

Usage has one method, add(), which folds another Usage into this one in place. AgentRoute uses it internally to roll each turn's cost into the running total, but it is also handy when you run several agents and want a combined figure:

from agentroute import Agent, Usage
 
planner = Agent(name="planner", model="claude-sonnet-4")
writer = Agent(name="writer", model="claude-sonnet-4")
 
total = Usage()
plan = planner.run("Outline a blog post about vector databases.")
total.add(plan.usage)
 
draft = writer.run(f"Write the post from this outline:\n{plan}")
total.add(draft.usage)
 
print(f"Combined cost: ${total.total_cost_usd:.4f}, calls: {total.model_calls}")

add() mutates the receiver and returns None, so accumulate into a long-lived Usage rather than chaining.

Accessing memory from a tool

When the agent has memory attached, ctx.memory exposes the same async surface inside your tools. A tool can persist a fact for later turns or look one up:

from agentroute import Agent, Context, Memory
 
agent = Agent(
    name="assistant",
    model="claude-sonnet-4",
    memory=Memory(),
)
 
@agent.tool
async def save_preference(ctx: Context, key: str, value: str) -> str:
    """Remember a user preference for later in the conversation."""
    await ctx.memory.remember(key, value)
    return f"Saved {key}."
 
@agent.tool
async def lookup_preference(ctx: Context, query: str) -> list[str]:
    """Recall previously saved preferences matching a query."""
    return await ctx.memory.recall(query, limit=5)

Because remember() and recall() are async, declare the tool async def and await them directly. Sync tools work too, but you cannot await from a sync function — reach for memory in async tools. The full memory model, including the persistent MemorySQLite backend, is covered in Memory.

Next steps