Results & events

Every call to Agent.run() and Agent.arun() returns a Result. This page documents that return type, the forthcoming Event type that future streaming will yield, and the ResultDeploy placeholder for future deployment.

For the conceptual walkthrough of reading output, usage, and the message transcript, see Results.

Result

Result — what an agent run gives you back: the final output plus everything the loop accumulated along the way.

from agentroute import Result

@dataclass
class Result:
    output: Any
    usage: Usage = Usage()
    messages: list[dict[str, Any]] = []
    interrupted: bool = False

Parameter	Type	Default	Description
`output`	Any	—	The agent's final answer. A `str` for text runs; an instance of your output model when the agent was created with `output=SomeModel`. See structured output.
`usage`	Usage	`Usage()`	Token and cost totals accumulated across every model call in the run.
`messages`	list[dict[str, Any]]	`[]`	The full OpenAI-style transcript of the run — system, user, assistant, and tool messages, including intermediate tool calls and their results.
`interrupted`	bool	`False`	Whether the run was cut short (for example by an approval gate that was denied) rather than completing normally.

ReturnsResult

Returned by both Agent.run() and Agent.arun().

String conversion

Result defines __str__ so print(result) shows the text without reaching for .output. It returns the empty string when output is None, otherwise str(self.output).

@dataclass
class Result:
    def __str__(self) -> str:
        return "" if self.output is None else str(self.output)

Tip

For programmatic use always read result.output — it preserves the real type (a model instance, a number, a list). str(result) is a convenience for printing and logging.

Examples

A plain text run. result.output is a str, and printing the Result shows it directly.

from agentroute import Agent
 
agent = Agent("assistant", model="claude-sonnet-4")
result = agent.run("Name three primary colors.")
 
print(result)                       # red, yellow, blue
print(result.output)                # red, yellow, blue
print(result.usage.total_cost_usd)  # 0.0004
print(result.usage.model_calls)     # 1
print(len(result.messages))         # transcript length, e.g. 3

A structured run. With output= set, result.output is an instance of your model.

from pydantic import BaseModel
from agentroute import Agent
 
 
class City(BaseModel):
    name: str
    country: str
 
 
agent = Agent("geographer", model="claude-sonnet-4", output=City)
result = agent.run("What is the capital of Japan?")
 
print(type(result.output))   # <class '__main__.City'>
print(result.output.name)    # Tokyo
print(result.output.country) # Japan

Inspecting the transcript and totals after a tool-using run.

from agentroute import Agent, tool
 
 
@tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b
 
 
agent = Agent("calculator", model="claude-sonnet-4", tools=[add])
result = agent.run("What is 19 + 23?")
 
print(result.output)               # 42
print(result.usage.input_tokens)   # prompt tokens across all calls
print(result.usage.output_tokens)  # completion tokens across all calls
 
for message in result.messages:
    print(message["role"])         # system, user, assistant, tool, assistant

See Usage for the full breakdown of the usage field.

Event

Event — a single streaming event. Events are yielded by a future agent.stream(); the type is defined now so the surface is stable.

from agentroute import Event

@dataclass
class Event:
    kind: EventKind
    data: dict[str, Any] = {}

Parameter	Type	Default	Description
`kind`	EventKind	—	Which kind of event this is — one of the literal values listed below.
`data`	dict[str, Any]	`{}`	Event-specific payload (for example, the text fragment for a `text_delta`, or the tool name and arguments for a `tool_call_start`).

EventKind

EventKind is a Literal enumerating the event kinds a stream can emit.

EventKind = Literal[
    "text_delta",
    "tool_call_start",
    "tool_call_end",
    "agent_start",
    "agent_end",
]

Kind	Emitted when
`agent_start`	The run begins.
`text_delta`	A fragment of the model's text answer arrives.
`tool_call_start`	The model invokes a tool.
`tool_call_end`	A tool finishes and its result is captured.
`agent_end`	The run completes.

Streaming is forthcoming

agent.stream() is not available yet — it is wired in a later phase. Event and EventKind are part of the public API today so streaming code written against them will keep working, but there is currently no method that yields Event values.

ResultDeploy

ResultDeploy — the return type for a future Agent.deploy(). It is a placeholder; deployment lands in a later phase.

from agentroute import ResultDeploy

@dataclass
class ResultDeploy:
    url: str
    status: str = "pending"
    agent_card_url: str | None = None

Parameter	Type	Default	Description
`url`required	str	—	Where the deployed agent will be reachable.
`status`	str	`"pending"`	Deployment state.
`agent_card_url`	str \| None	`None`	URL of the agent's metadata card, if one is published.

Not yet available

Agent.deploy() is a later-phase feature. ResultDeploy defines the shape its result will take, but there is no deployment method to call today.