> ## Documentation Index
> Fetch the complete documentation index at: https://spacesail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Agents

> Learn how to run Agno Agents.

Run your Agent by calling `Agent.run()` or `Agent.arun()`. Here's how they work:

1. The agent builds the context to send to the model (system message, user message, chat history, user memories, session state and other relevant inputs).
2. The agent sends this context to the model.
3. The model processes the input and responds with either a message or a tool call.
4. If the model makes a tool call, the agent executes it and returns the results to the model.
5. The model processes the updated context, repeating this loop until it produces a final message without any tool calls.
6. The agent returns this final response to the caller.

## Basic Execution

The `Agent.run()` function runs the agent and returns the output — either as a `RunOutput` object or as a stream of `RunOutputEvent` objects (when `stream=True`). For example:

```python theme={null}
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)
```

<Tip>
  You can also run the agent asynchronously using `Agent.arun()`. See
  this [example](/examples/concepts/agent/async/basic).
</Tip>

## 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:

```python theme={null}
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)
```

<Tip>
  See the [Input & Output](/concepts/agents/input-output) docs for more information, and to see how to use structured input and output with agents.
</Tip>

## 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](/concepts/agents/metrics).
* `model`: The model used for the run.

See detailed documentation in the [RunOutput](/reference/agents/run-response) documentation.

## Streaming

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

```python theme={null}
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)
```

<Tip>
  For asynchronous streaming, see this [example](/examples/concepts/agent/async/streaming).
</Tip>

### Streaming all events

By default, when you stream a response, only the `RunContent` events will be streamed.

You can also stream all run events by setting `stream_events=True`.

This will provide real-time updates about the agent's internal processes, like tool calling or reasoning:

. For example:

```python theme={null}
# Stream all events
response_stream: Iterator[RunOutputEvent] = agent.run(
    "Trending products",
    stream=True,
    stream_events=True
)
```

### Handling Events

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

```python theme={null}
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.content}")
```

<Check>
  RunEvents make it possible to build exceptional agent experiences.
</Check>

### Event Types

The following events are yielded by the `Agent.run()` and `Agent.arun()` functions depending on the agent's 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. This is 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 |

#### 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

If you are using your own custom tools, you can yield custom events along with the rest of the Agno events. Create a custom event class by extending the `CustomEvent` class. For example:

```python theme={null}
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. For example:

```python theme={null}
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](/examples/concepts/agent/events/custom_events) for more details.

## Specify Run 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:

```python theme={null}
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](/concepts/agents/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:

```python theme={null}
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](/concepts/multimodal) 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](/concepts/hitl) documentation.

## Cancelling a Run

A run can be cancelled by calling the `Agent.cancel_run()` method.

See more details in the [Cancelling a Run](/concepts/agents/run-cancel) documentation.

## Developer Resources

* View the [Agent reference](/reference/agents/agent)
* View the [RunOutput schema](/reference/agents/run-response)
* View [Agent Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/agents/README.md)