Run your Agent by calling Agent.run() or Agent.arun(). The execution flow:
- The agent builds context to send to the model (system message, user message, chat history, user memories, session state, and other relevant inputs).
- The agent sends this context to the model.
- The model responds with either a message or a tool call.
- If the model makes a tool call, the agent executes it and returns results to the model.
- The model processes the updated context, repeating this loop until it produces a final message without tool calls.
- The agent returns this final response to the caller.
Basic Execution
Agent.run() returns a RunOutput object, or a stream of RunOutputEvent objects when stream=True:
from agno.agent import Agent, RunOutput
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
from agno.utils.pprint import pprint_run_response
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
# Run agent and return the response as a variable
response: RunOutput = agent.run("Trending startups and products.")
# Print the response in markdown format
pprint_run_response(response, markdown=True)
Run the agent asynchronously using Agent.arun(). See this example. input parameter can be a string, list, dictionary, message, Pydantic model, or list of messages:
from agno.agent import Agent, RunOutput
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
from agno.utils.pprint import pprint_run_response
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
# Run agent with input="Trending startups and products."
response: RunOutput = agent.run(input="Trending startups and products.")
# Print the response in markdown format
pprint_run_response(response, markdown=True)
Run Output
Agent.run() returns a RunOutput object when not streaming. Core attributes:
run_id: The ID of the run.agent_id: The ID of the agent.agent_name: The name of the agent.session_id: The ID of the session.user_id: The ID of the user.content: The response content.content_type: The type of content. For structured output, this is the class name of the Pydantic model.reasoning_content: The reasoning content.messages: The list of messages sent to the model.metrics: The metrics of the run. See Metrics.model: The model used for the run.
See RunOutput reference for full documentation.
Streaming
Set stream=True to return an iterator of RunOutputEvent objects:
from typing import Iterator
from agno.agent import Agent, RunOutputEvent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
# Run agent and return the response as a stream
stream: Iterator[RunOutputEvent] = agent.run("Trending products", stream=True)
for chunk in stream:
if chunk.event == RunEvent.run_content:
print(chunk.content)
For asynchronous streaming, see this example. Streaming Events
By default, only RunContent events (model responses) are streamed.
To stream all events (tool calls, reasoning, memory updates, etc.), set stream_events=True:
response_stream: Iterator[RunOutputEvent] = agent.run(
"Trending products",
stream=True,
stream_events=True
)
Handling Events
Process events as they arrive:
from agno.agent import Agent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
stream = agent.run("Trending products", stream=True, stream_events=True)
for chunk in stream:
if chunk.event == RunEvent.run_content:
print(f"Content: {chunk.content}")
elif chunk.event == RunEvent.tool_call_started:
print(f"Tool call started: {chunk.tool.tool_name}")
elif chunk.event == RunEvent.reasoning_step:
print(f"Reasoning step: {chunk.reasoning_content}")
RunEvents give you complete visibility into the agent’s internal processes, enabling rich UI feedback and debugging.
Event Types
Events yielded by Agent.run() and Agent.arun(), depending on agent configuration:
Core Events
| Event Type | Description |
|---|
RunStarted | Indicates the start of a run |
RunContent | Contains the model’s response text as individual chunks |
RunContentCompleted | Signals completion of content streaming |
RunIntermediateContent | Contains the model’s intermediate response text as individual chunks. Used when output_model is set. |
RunCompleted | Signals successful completion of the run |
RunError | Indicates an error occurred during the run |
RunCancelled | Signals that the run was cancelled |
Control Flow Events
| Event Type | Description |
|---|
RunPaused | Indicates the run has been paused |
RunContinued | Signals that a paused run has been continued |
| Event Type | Description |
|---|
ToolCallStarted | Indicates the start of a tool call |
ToolCallCompleted | Signals completion of a tool call, including tool call results |
Reasoning Events
| Event Type | Description |
|---|
ReasoningStarted | Indicates the start of the agent’s reasoning process |
ReasoningStep | Contains a single step in the reasoning process |
ReasoningCompleted | Signals completion of the reasoning process |
Memory Events
| Event Type | Description |
|---|
MemoryUpdateStarted | Indicates that the agent is updating its memory |
MemoryUpdateCompleted | Signals completion of a memory update |
Session Summary Events
| Event Type | Description |
|---|
SessionSummaryStarted | Indicates the start of session summary generation |
SessionSummaryCompleted | Signals completion of session summary generation |
Pre-Hook Events
| Event Type | Description |
|---|
PreHookStarted | Indicates the start of a pre-run hook |
PreHookCompleted | Signals completion of a pre-run hook execution |
Post-Hook Events
| Event Type | Description |
|---|
PostHookStarted | Indicates the start of a post-run hook |
PostHookCompleted | Signals completion of a post-run hook execution |
Parser Model Events
| Event Type | Description |
|---|
ParserModelResponseStarted | Indicates the start of the parser model response |
ParserModelResponseCompleted | Signals completion of the parser model response |
Output Model Events
| Event Type | Description |
|---|
OutputModelResponseStarted | Indicates the start of the output model response |
OutputModelResponseCompleted | Signals completion of the output model response |
Custom Events
Create custom events by extending CustomEvent:
from dataclasses import dataclass
from agno.run.agent import CustomEvent
from typing import Optional
@dataclass
class CustomerProfileEvent(CustomEvent):
"""CustomEvent for customer profile."""
customer_name: Optional[str] = None
customer_email: Optional[str] = None
customer_phone: Optional[str] = None
from agno.tools import tool
@tool()
async def get_customer_profile():
"""Example custom tool that simply yields a custom event."""
yield CustomerProfileEvent(
customer_name="John Doe",
customer_email="[email protected]",
customer_phone="1234567890",
)
Specify Run User and Session
Pass user_id and session_id to associate a run with a specific user and session:
agent.run("Tell me a 5 second short story about a robot", user_id="[email protected]", session_id="session_123")
Passing Images / Audio / Video / Files
Pass media via images, audio, video, or files parameters:
agent.run("Tell me a 5 second short story about this image", images=[Image(url="https://example.com/image.jpg")])
Passing Output Schema
Pass an output schema for structured output:
from pydantic import BaseModel
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
class TVShow(BaseModel):
title: str
episodes: int
agent = Agent(model=OpenAIResponses(id="gpt-5.2"))
agent.run("Create a TV show", output_schema=TVShow)
Pausing and Continuing a Run
An agent run can be paused for human-in-the-loop flows. Continue execution with Agent.continue_run().
See Human-in-the-Loop for more details.
Cancelling a Run
Cancel a run with Agent.cancel_run().
See Cancelling a Run for more details.
Developer Resources
