agency-swarm-cn-git/docs/additional-features/observability.mdx

---
title: "Observability"
description: "Track and analyze your agent performance and behavior by connecting with third party observability tools."
icon: "eyes"
---

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
{
  "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
        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
        pip install langfuse
        ```
      </Step>
      <Step title="Set Environment Variables">
        ```bash
        export LANGFUSE_SECRET_KEY=<your-secret-key>
        export LANGFUSE_PUBLIC_KEY=<your-public-key>
        export LANGFUSE_HOST=<your-host>
        ```
      </Step>
      <Step title="Implementation">
        ```python
        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
        pip install agentops
        ```
      </Step>
      <Step title="Set Environment Variables">
        ```bash
        export AGENTOPS_API_KEY=<your-api-key>
        ```
      </Step>
      <Step title="Implementation">
        ```python
        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
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)