The Agent.run() function runs the agent and generates a response, either as a RunOutput object or a stream of RunOutputEvent 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 Agents

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.
For development purposes, you can also print the response in the terminal using the Agent.print_response() method. 
agent.print_response("Tell me a 5 second short story about a robot")

# Or for streaming
agent.print_response("Tell me a 5 second short story about a robot", stream=True)
The Agent.print_response() method is a helper method that uses the Agent.run() method under the hood. This is only for convenience during development and not recommended for production use.See the Agent class reference for more details.

​
Typed inputs and outputs

An agent can be provided with typed input (i.e a pydantic model) by passing it in the Agent.run() or Agent.print_response() as the input parameter. 
from typing import List

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.hackernews import HackerNewsTools
from pydantic import BaseModel, Field


class ResearchTopic(BaseModel):
    """Structured research topic with specific requirements"""

    topic: str
    focus_areas: List[str] = Field(description="Specific areas to focus on")
    target_audience: str = Field(description="Who this research is for")
    sources_required: int = Field(description="Number of sources needed", default=5)

hackernews_agent = Agent(
    name="Hackernews Agent",
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[HackerNewsTools()],
    role="Extract key insights and content from Hackernews posts",
)

hackernews_agent.print_response(
    input=ResearchTopic(
        topic="AI",
        focus_areas=["AI", "Machine Learning"],
        target_audience="Developers",
        sources_required=5,
    )
)
You can set the input_schema on the agent to validate the input. See more details in the Input and Output documentation.
In addition, you can set the output_schema on the agent to specify typed output.
hackernews_agent.py
from pydantic import BaseModel, Field
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.hackernews import HackerNewsTools

class HackernewsReport(BaseModel):
    title: str = Field(..., description="Title of the Hackernews article.")
    subtitle: str = Field(..., description="Subtitle of the Hackernews article.")
    content: str = Field(..., description="Content of the Hackernews article.")

hackernews_agent = Agent(
    name="Hackernews Agent",
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[HackerNewsTools()],
    role="Extract key insights and content from Hackernews posts and write a report about it.",
    output_schema=HackernewsReport,
)

hackernews_agent.print_response("Latest happening in the world of AI")
See more details in the Input and Output documentation.

​
RunOutput

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.

​
Interactive CLI

You can also interact with the agent via a CLI. 
agent.cli_app(input="Tell me a 5 second short story about a robot", stream=True)
See the Agent class reference for more details.

​
Developer Resources