> ## Documentation Index
> Fetch the complete documentation index at: https://agent-observability-docs.splunk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Splunk Agent Observability to a CrewAI Application

> Learn how to add logging and evaluations with Splunk Agent Observability to an existing CrewAI application

## Overview

This guide explains how to add logging and evaluations with Splunk Agent Observability to an existing CrewAI application.

In this guide you will:

1. [Set up a project with Splunk Agent Observability](#install-dependencies)
2. [Load environment variables if necessary](#load-environment-variables-if-necessary)
3. [Add the Splunk Agent Observability event listener](#add-the-splunk-agent-observability-event-listener)
4. [Run your crew](#run-your-crew)

## Before you start

To complete this how-to, you will need:

* An agentic application built with [CrewAI](https://www.crewai.com). This guide assumes you have a `run()` function as your entry point.
  > If you don't have a CrewAI application, you can follow the [**Build your first Crew** guide from the CrewAI documentation](https://docs.crewai.com/en/guides/crews/first-crew).
* A [Splunk Agent Observability project](/concepts/projects.md) configured, with [relevant evaluators configured](/concepts/evaluators/overview.md)
* Your [Splunk Agent Observability API key](/references/faqs/find-keys.md#splunk-ao-api-key)

## Install dependencies

To use Splunk Agent Observability, you need to install some package dependencies, and configure environment variables.

**1. Install Required Dependencies**

Install the required dependencies for your app. Create a virtual environment using your preferred method, then install dependencies inside that environment using your preferred tool:

```bash Pip theme={null}
pip install splunk-ao
```

```bash uv theme={null}
uv pip install splunk-ao
```

```bash Poetry theme={null}
poetry add splunk-ao
```

Install `python-dotenv` if you don't already have this installed.

```bash Pip theme={null}
pip install python-dotenv
```

```bash uv theme={null}
uv pip install python-dotenv
```

```bash Poetry theme={null}
poetry add python-dotenv
```

**2. Create a .env file if you don't have one already, and add the following values**

**On-premises**

```ini .env theme={null}
# On-premises, standalone, custom deployments
SPLUNK_AO_API_KEY="your-splunk-ao-api-key"
SPLUNK_AO_CONSOLE_URL="your-splunk-ao-url"

# Your Splunk Agent Observability project name
SPLUNK_AO_PROJECT="your-splunk-ao-project-name"

# The name of the Agent Stream you want to use for logging
SPLUNK_AO_AGENT_STREAM="your-splunk-ao-agent-stream"
```

> [!NOTE]
>
> If you're using the free version of Splunk Agent Observability, the `SPLUNK_AO_CONSOLE_URL` environment variable isn't needed.

For more information on these environment variables, see [Find Your Organization Keys](/references/faqs/find-keys.md).

**SaaS**

```ini .env theme={null}
# SaaS (Splunk Observability Cloud) deployments
SPLUNK_AO_O11Y_TOKEN="your-splunk-o11y-token"
SPLUNK_AO_REALM="your-splunk-o11y-deployment-realm"

# Your Splunk Agent Observability project name
SPLUNK_AO_PROJECT="your-splunk-ao-project-name"

# The name of the Agent Stream you want to use for logging
SPLUNK_AO_AGENT_STREAM="your-splunk-ao-agent-stream"
```

For more information on these environment variables, see [Find Your Organization Keys](/references/faqs/find-keys.md#saas).

> [!NOTE]
>
> This assumes you are using a free Splunk Agent Observability account. If you are using an on-premises, standalone, or custom deployment, then you will also need to add your Splunk Agent Observability URL:
>
> ```ini .env theme={null}
> SPLUNK_AO_CONSOLE_URL=your-splunk-ao-url
> ```

## Load environment variables if necessary

Splunk Agent Observability needs values like the API key and project name set as environment variables. If you are not already loading a `.env` file, then you need to do so.

> [!NOTE]
>
> You can skip this step if you are already loading the `.env` file.

**1. Import the dotenv package**

Add the following code at the top of your `main.py` file to import `dotenv` and load the `.env` file.

```python Python theme={null}
from dotenv import load_dotenv
load_dotenv()
```

> [!NOTE]
>
> This assumes you are following the same structure as the sample CrewAI applications. If you are not, add this to the top of the file that contains the entry point of your application.

## Add the Splunk Agent Observability event listener

To enable logging with Splunk Agent Observability, you need to create an instance of the `CrewAIEventListener`.

**1. Import the Splunk Agent Observability CrewAI handler package**

Add the following code at the top of your `main.py` file:

```python Python theme={null}
from splunk_ao.handlers.crewai.handler import CrewAIEventListener
```

> [!NOTE]
>
> This assumes you are following the same structure as the sample CrewAI applications. If you are not, add this to the top of the file that contains the entry point of your application.

**2. Create the event listener**

At the start of your `run` function, create the event listener:

```python Python theme={null}
def run():
    # Create the event listener
    CrewAIEventListener()

    # The rest of your existing code goes here
```

When you create the listener instance, it is automatically registered with CrewAI.

## Run your crew

You are now ready to run your crew, and see the logged traces in Splunk Agent Observability.

**1. Run your crew**

Run your crew with the CrewAI CLI:

```bash Terminal theme={null}
crewai run
```

**2. View the traces in Splunk Agent Observability**

Once your crew has finished, the traces will be flushed an appear in Splunk Agent Observability.

For more information on viewing traces in the UI, see [Where can I find my sessions?](/concepts/logging/sessions/sessions-overview.md#where-can-i-find-my-sessions)

## See also

* [Splunk Agent Observability CrewAI event listener](/sdk-api/third-party-integrations/crewai/crewai.md)
* [`CrewAIEventListener` Python SDK reference](/sdk-api/python/reference/handlers/crewai/handler)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.