> ## Documentation Index
> Fetch the complete documentation index at: https://agency-swarm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> Track and analyze your agent performance and behavior by connecting with third party observability tools.

Agency Swarm supports multiple observability approaches to help you track and analyze your agent's behavior and performance.

## Usage Payload

When usage tracking is enabled, responses include a `usage` object with token counts and cost.

```json theme={null}
{
  "response": "Test response",
  "new_messages": [],
  "usage": {
    "request_count": 1,
    "cached_tokens": 0,
    "input_tokens": 10,
    "output_tokens": 20,
    "total_tokens": 30,
    "total_cost": 0.0
  }
}
```

**Fields:**

* `request_count`: Number of model requests
* `cached_tokens`: Tokens served from cache (if available)
* `input_tokens`: Tokens sent to the model
* `output_tokens`: Tokens generated by the model
* `total_tokens`: Total tokens for the request
* `total_cost`: Estimated cost (USD)
* `reasoning_tokens` (optional): Reasoning tokens (if available)

**Where you'll see it:**

* [FastAPI Integration](/additional-features/fastapi-integration): `POST /get_response` returns JSON with `usage`, and the final `event: messages` in `POST /get_response_stream` includes `usage`.
* [Running an Agency](/core-framework/agencies/running-agency#track-usage-and-cost): use `/cost` in the TUI to see session usage and cost.

## Supported Observability Platforms

Agency Swarm supports three main observability approaches:

<CardGroup cols={3}>
  <Card title="OpenAI Tracing" icon="chart-line" href="#openai-tracing">
    Built-in tracing using OpenAI's native tools
  </Card>

  <Card title="Langfuse" icon="gauge-high" href="#langfuse-tracing">
    Advanced tracing and debugging platform
  </Card>

  <Card title="AgentOps" icon="database" href="#agentops-tracing">
    Specialized agent monitoring and analytics
  </Card>
</CardGroup>

## Getting Started

Let's walk through setting up each tracing solution. You can use them individually or combine them for monitoring.

<Tabs>
  <Tab title="OpenAI Tracing">
    <Steps>
      <Step title="Basic Setup">
        OpenAI tracing is built into Agency Swarm and requires no additional packages.
      </Step>

      <Step title="Implementation">
        ```python theme={null}
        from agency_swarm import trace

        async def openai_tracing(input_message: str) -> str:
            agency_instance = create_agency()
            with trace("OpenAI tracing"):
                response = await agency_instance.get_response(message=input_message)
            return response.final_output
        ```
      </Step>

      <Step title="View Traces">
        After running your code, view your traces at [platform.openai.com/traces](https://platform.openai.com/traces)
      </Step>
    </Steps>
  </Tab>

  <Tab title="Langfuse">
    <Steps>
      <Step title="Install Package">
        ```bash theme={null}
        pip install langfuse
        ```
      </Step>

      <Step title="Set Environment Variables">
        ```bash theme={null}
        export LANGFUSE_SECRET_KEY=<your-secret-key>
        export LANGFUSE_PUBLIC_KEY=<your-public-key>
        export LANGFUSE_HOST=<your-host>
        ```
      </Step>

      <Step title="Implementation">
        ```python theme={null}
        from langfuse import observe

        @observe()
        async def langfuse_tracing(input_message: str) -> str:
            agency_instance = create_agency()

            @observe()
            async def get_response_wrapper(message: str):
                return await agency_instance.get_response(message=message)

            response = await get_response_wrapper(input_message)
            return response.final_output
        ```
      </Step>

      <Step title="View Traces">
        Access your traces at [cloud.langfuse.com](https://cloud.langfuse.com) and select your project.
      </Step>
    </Steps>
  </Tab>

  <Tab title="AgentOps">
    <Steps>
      <Step title="Install Package">
        ```bash theme={null}
        pip install agentops
        ```
      </Step>

      <Step title="Set Environment Variables">
        ```bash theme={null}
        export AGENTOPS_API_KEY=<your-api-key>
        ```
      </Step>

      <Step title="Implementation">
        ```python theme={null}
        import agentops

        async def agentops_tracing(input_message: str) -> str:
            agentops.init(
                auto_start_session=True,
                trace_name="Agentops tracing",
                tags=["openai", "agentops-example"]
            )
            tracer = agentops.start_trace(
                trace_name="Agentops tracing",
                tags=["openai", "agentops-example"]
            )

            agency_instance = create_agency()
            response = await agency_instance.get_response(message=input_message)

            agentops.end_trace(tracer, end_state="Success")
            return response.final_output
        ```
      </Step>

      <Step title="View Traces">
        When you run your code, AgentOps will print a session replay URL in the console that looks like: `https://app.agentops.ai/sessions?trace_id=<your-trace-id>`
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Implementation Example

For a complete working example that demonstrates all three tracing methods with a multi-agent agency, see [observability.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/observability.py) in the examples directory.

The example shows:

* How to set up a basic agency with CEO, Developer, and Data Analyst roles
* Implementation of all three tracing methods (OpenAI, Langfuse, AgentOps)
* A sample tool for data analysis
* Error handling and proper tracing setup

You can run the example with:

```bash theme={null}
python examples/observability_demo.py
```

For more information about each platform's capabilities and configuration options, refer to their respective documentation:

* [OpenAI Documentation](https://platform.openai.com/docs)
* [Langfuse Documentation](https://langfuse.com/docs)
* [AgentOps Documentation](https://docs.agentops.ai)