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

​
Running Agents

​
Basic Execution

Here’s how to run your agent. The response is captured in the response. 
from agno.agent import Agent, RunOutput
from agno.models.openai import OpenAIChat
from agno.utils.pprint import pprint_run_response

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

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

# Print the response in markdown format
pprint_run_response(response, markdown=True)
You can also run the agent asynchronously using the Agent.arun() method. See the Async Agent example.

​
Run Input

The input parameter is the input to send to the agent. It can be a string, a list, a dictionary, a message, a pydantic model or a list of messages. For example: 
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-5-mini"),
    description="You write movie scripts.",
)

response = agent.run("Write movie script about a girl living in New York")
pprint_run_response(response, markdown=True)
The pprint_run_response utility is a helper function that prints the response on your terminal.
For more information, and to see how to use structured input and output with agents, see the Input & Output documentation.

​
Run Output

The Agent.run() function returns a RunOutput object when not streaming. Here are some of the 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. In the case of structured output, this will be 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. For more details see Metrics.
  • model: The model used for the run.
See detailed documentation in the RunOutput documentation.

​
Streaming Responses

To enable streaming, set stream=True when calling run(). This will return an iterator of RunOutputEvent objects instead of a single response. 
from typing import Iterator
from agno.agent import Agent, RunOutputEvent
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[RunOutputEvent] = 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)
You can also run the agent asynchronously using the Agent.arun() method. See the Async Agent Streaming example.

​
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[RunOutputEvent] = 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("Tell me a 5 second short story about a lion", stream=True, stream_intermediate_steps=True)

for event in response_stream:
    if event.event == "RunContent":
        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 the AgentOS UI.

​
Storing Events

You can store all the events that happened during a run on the RunOutput 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-5-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 response.events:
    print(event.event)
By default the RunContentEvent event is not stored (because it would be very verbose). You can modify which events are skipped by setting the events_to_skip parameter. For example: 
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.run.agent import RunEvent

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

​
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
RunContentContains the model’s response text as individual chunks
RunIntermediateContentContains the model’s intermediate response text as individual chunks. This is used when output_model is set.
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

​
Parser Model events

Event TypeDescription
ParserModelResponseStartedIndicates the start of the parser model response
ParserModelResponseCompletedSignals completion of the parser model response

​
Output Model events

Event TypeDescription
OutputModelResponseStartedIndicates the start of the output model response
OutputModelResponseCompletedSignals completion of the output model response

​
Custom Events

If you are using your own custom tools, it will often be useful to be able to yield custom events. Your custom events will be yielded together with the rest of the expected Agno events. We recommend creating your custom event class extending the built-in CustomEvent class: 
from dataclasses import dataclass
from agno.run.agent import CustomEvent

@dataclass
class CustomerProfileEvent(CustomEvent):
    """CustomEvent for customer profile."""

    customer_name: Optional[str] = None
    customer_email: Optional[str] = None
    customer_phone: Optional[str] = None
You can then yield your custom event from your tool. The event will be handled internally as an Agno event, and you will be able to access it in the same way you would access any other Agno event. 
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",
    )
See the full example for more details.

​
Options When Running an Agent

​
Specify the User and Session

You can specify which user and session to use when running the agent by passing the user_id and session_id parameters. This ensures the current run is associated with the correct user and session. For example: 
agent.run("Tell me a 5 second short story about a robot", user_id="john@example.com", session_id="session_123")
For more information see the Agent Sessions documentation.

​
Passing Images / Audio / Video / Files

You can pass images, audio, video, or files to the agent by passing the images, audio, video, or files parameters. For example: 
agent.run("Tell me a 5 second short story about this image", images=[Image(url="https://example.com/image.jpg")])
For more information see the Multimodal Agents documentation.

​
Pausing and Continuing a Run

An agent run can be paused when a human-in-the-loop flow is initiated. You can then continue the execution of the agent by calling the Agent.continue_run() method. See more details in the Human-in-the-Loop documentation.

​
Cancelling a Run

A run can be cancelled by calling the Agent.cancel_run() method. See more details in the Cancelling a Run documentation.

​
Developer Resources