The Agent.run() function runs the agent and generates a response, either as a RunResponse object or a stream of RunResponse objects.

Many of our examples use agent.print_response() which is a helper utility to print the response in the terminal. It uses agent.run() under the hood.

Running your Agent

Here’s how to run your agent. The response is captured in the response.

from typing import Iterator
from agno.agent import Agent, RunResponse
from agno.models.openai import OpenAIChat
from agno.utils.pprint import pprint_run_response

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))

# Run agent and return the response as a variable
response: RunResponse = agent.run("Tell me a 5 second short story about a robot")

# Print the response in markdown format
pprint_run_response(response, markdown=True)

RunResponse

The Agent.run() function returns a RunResponse object when not streaming. It has the following attributes:

Understanding Metrics

For a detailed explanation of how metrics are collected and used, please refer to the Metrics Documentation.

See detailed documentation in the RunResponse documentation.

Streaming Responses

To enable streaming, set stream=True when calling run(). This will return an iterator of RunResponseEvent objects instead of a single response.

From agno version 1.6.0, the Agent.run() function returns an iterator of RunResponseEvent, not of RunResponse objects.

from typing import Iterator
from agno.agent import Agent, RunResponseEvent
from agno.models.openai import OpenAIChat
from agno.utils.pprint import pprint_run_response

agent = Agent(model=OpenAIChat(id="gpt-4-mini"))

# Run agent and return the response as a stream
response_stream: Iterator[RunResponseEvent] = agent.run(
    "Tell me a 5 second short story about a lion",
    stream=True
)

# Print the response stream in markdown format
pprint_run_response(response_stream, markdown=True)

Streaming Intermediate Steps

For even more detailed streaming, you can enable intermediate steps by setting stream_intermediate_steps=True. This will provide real-time updates about the agent’s internal processes.

# Stream with intermediate steps
response_stream: Iterator[RunResponseEvent] = agent.run(
    "Tell me a 5 second short story about a lion",
    stream=True,
    stream_intermediate_steps=True
)

Handling Events

You can process events as they arrive by iterating over the response stream:

response_stream = agent.run("Your prompt", stream=True, stream_intermediate_steps=True)

for event in response_stream:
    if event.event == "RunResponseContent":
        print(f"Content: {event.content}")
    elif event.event == "ToolCallStarted":
        print(f"Tool call started: {event.tool}")
    elif event.event == "ReasoningStep":
        print(f"Reasoning step: {event.content}")
    ...

You can see this behavior in action in our Playground.

Storing Events

You can store all the events that happened during a run on the RunResponse object.

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.utils.pprint import pprint_run_response

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"), store_events=True)

response = agent.run("Tell me a 5 second short story about a lion", stream=True, stream_intermediate_steps=True)
pprint_run_response(response)

for event in agent.run_response.events:
    print(event.event)

By default the RunResponseContentEvent event is not stored. You can modify which events are skipped by setting the events_to_skip parameter.

For example:

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"), store_events=True, events_to_skip=[RunEvent.run_started.value])

Event Types

The following events are yielded by the Agent.run() and Agent.arun() functions depending on the agent’s configuration:

Core Events

Event TypeDescription
RunStartedIndicates the start of a run
RunResponseContentContains the model’s response text as individual chunks
RunCompletedSignals successful completion of the run
RunErrorIndicates an error occurred during the run
RunCancelledSignals that the run was cancelled

Control Flow Events

Event TypeDescription
RunPausedIndicates the run has been paused
RunContinuedSignals that a paused run has been continued

Tool Events

Event TypeDescription
ToolCallStartedIndicates the start of a tool call
ToolCallCompletedSignals completion of a tool call, including tool call results

Reasoning Events

Event TypeDescription
ReasoningStartedIndicates the start of the agent’s reasoning process
ReasoningStepContains a single step in the reasoning process
ReasoningCompletedSignals completion of the reasoning process

Memory Events

Event TypeDescription
MemoryUpdateStartedIndicates that the agent is updating its memory
MemoryUpdateCompletedSignals completion of a memory update

See detailed documentation in the RunResponseEvent documentation.