Running Agents

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.

Run Input

The 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)

See Input & Output for structured input and output.

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}")

Run events expose each step of the run as it happens. Use them for live UI updates 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

Tool Events

Event Type	Description
`ToolCallStarted`	Indicates the start of a tool call
`ToolCallCompleted`	Signals completion of a tool call, including tool call results
`ToolCallError`	Indicates a tool call failed, including the error

Reasoning Events

Event Type	Description
`ReasoningStarted`	Indicates the start of the agent’s reasoning process
`ReasoningStep`	Contains a single step in the reasoning process
`ReasoningContentDelta`	Contains a chunk of streamed reasoning content
`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

Model Request Events

Event Type	Description
`ModelRequestStarted`	Indicates the start of a model request
`ModelRequestCompleted`	Signals completion of a model request, including token metrics

Compression Events

Event Type	Description
`CompressionStarted`	Indicates the start of tool result compression
`CompressionCompleted`	Signals completion of tool result compression

Followup Events

Event Type	Description
`FollowupsStarted`	Indicates the start of followup suggestion generation
`FollowupsCompleted`	Signals completion of followup generation, including the suggestions

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

Yield custom events from your tool:

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="john.doe@example.com",
        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="john@example.com", session_id="session_123")

See Agent Sessions for more details.

Passing Images / Audio / Video / Files

Pass media via images, audio, videos, or files parameters:

from agno.media import Image

agent.run("Tell me a 5 second short story about this image", images=[Image(url="https://example.com/image.jpg")])

See Multimodal Agents for more details.

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)

See Input & Output for more details.

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.

Background Execution

Run agents in the background with Agent.arun(background=True). The agent continues running even if the client disconnects. Combine with stream=True for resumable SSE streaming with automatic event buffering and reconnection. See Background Execution for polling, resumable streaming, and the /resume endpoint.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Running Agents

Basic Execution

Run Input

Run Output

Streaming

Streaming Events

Handling Events

Event Types

Core Events

Control Flow Events

Tool Events

Reasoning Events

Memory Events

Session Summary Events

Pre-Hook Events

Post-Hook Events

Parser Model Events

Output Model Events

Model Request Events

Compression Events

Followup Events

Custom Events

Specify Run User and Session

Passing Images / Audio / Video / Files

Passing Output Schema

Pausing and Continuing a Run

Cancelling a Run

Background Execution

Developer Resources

​Basic Execution

​Run Input

​Run Output

​Streaming

​Streaming Events

​Handling Events

​Event Types

​Core Events

​Control Flow Events

​Tool Events

​Reasoning Events

​Memory Events

​Session Summary Events

​Pre-Hook Events

​Post-Hook Events

​Parser Model Events

​Output Model Events

​Model Request Events

​Compression Events

​Followup Events

​Custom Events

​Specify Run User and Session

​Passing Images / Audio / Video / Files

​Passing Output Schema

​Pausing and Continuing a Run

​Cancelling a Run

​Background Execution

​Developer Resources

Basic Execution

Run Input

Run Output

Streaming

Streaming Events

Handling Events

Event Types

Core Events

Control Flow Events

Tool Events

Reasoning Events

Memory Events

Session Summary Events

Pre-Hook Events

Post-Hook Events

Parser Model Events

Output Model Events

Model Request Events

Compression Events

Followup Events

Custom Events

Specify Run User and Session

Passing Images / Audio / Video / Files

Passing Output Schema

Pausing and Continuing a Run

Cancelling a Run

Background Execution

Developer Resources