> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# BeeAI (tracing)

> Trace BeeAI agent workflows with Respan — auto-instrumented spans, gateway routing, and full observability.

[BeeAI](https://framework.beeai.dev/introduction/welcome) is an open-source framework for building production-ready AI agents with memory, tools, and LLM integrations. Respan gives you visibility into BeeAI workflow spans, agent runs, LLM calls, and tool calls — and gateway routing through the OpenAI-compatible Respan endpoint.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [BeeAI gateway setup](/docs/integrations/gateway/bee-ai) to route this integration through the Respan gateway.

#### Example projects

* [Example project repository](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

**`Python`**

```bash Python
pip install respan-ai respan-instrumentation-beeai beeai-framework
```

**`TypeScript`**

```bash TypeScript
npm install @respan/respan @respan/tracing @respan/instrumentation-beeai @arizeai/openinference-instrumentation-beeai beeai-framework@0.1.13 @ai-sdk/openai@^1.3.13 zod@^3.24.2
```

`@arizeai/openinference-instrumentation-beeai` currently instruments `beeai-framework >=0.1.9 <0.1.14`. Use `beeai-framework@0.1.13` for compatible TypeScript tracing.

#### Set environment variables

**`Python`**

```bash Python
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

**`TypeScript`**

```bash TypeScript
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"
export RESPAN_MODEL="gpt-4o"
```

Python uses `OPENAI_API_KEY` for LLM requests and `RESPAN_API_KEY` for trace export. TypeScript can route LLM calls through the Respan gateway with `RESPAN_API_KEY`, or you can set `RESPAN_GATEWAY_API_KEY` separately.

#### Initialize and run

**`Python`**

```python Python
import asyncio
import os
from dotenv import load_dotenv

load_dotenv()

from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.backend import ChatModel
from respan import Respan
from respan_instrumentation_beeai import BeeAIInstrumentor

respan = Respan(
    app_name="beeai-python-example",
    instrumentations=[BeeAIInstrumentor()],
)


async def main() -> None:
    agent = RequirementAgent(
        llm=ChatModel.from_name(os.getenv("BEEAI_MODEL", "openai:gpt-4.1-nano")),
        role="observability assistant",
        instructions="Answer clearly and concisely.",
    )
    response = await agent.run(
        "Explain why traces help agent debugging in one sentence."
    )
    print(response.last_message.text)


asyncio.run(main())
```

**`TypeScript`**

```typescript TypeScript
import * as beeaiFramework from "beeai-framework";
import { OpenAIChatModel } from "beeai-framework/adapters/openai/backend/chat";
import { UserMessage } from "beeai-framework/backend/message";
import { Respan } from "@respan/respan";
import { BeeAIInstrumentor } from "@respan/instrumentation-beeai";

const gatewayBaseURL =
  process.env.RESPAN_GATEWAY_BASE_URL ??
  process.env.RESPAN_BASE_URL ??
  "https://api.respan.ai/api";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  appName: "beeai-typescript-example",
  instrumentations: [new BeeAIInstrumentor({ sdkModule: beeaiFramework })],
});
await respan.initialize();

const llm = new OpenAIChatModel(
  process.env.RESPAN_MODEL ?? "gpt-4o",
  {},
  {
    apiKey: process.env.RESPAN_GATEWAY_API_KEY ?? process.env.RESPAN_API_KEY,
    baseURL: gatewayBaseURL,
  },
);

const prompt = "Explain why traces help agent debugging in one sentence.";
const answer = await respan.withWorkflow(
  { name: "beeai_basic_chat.workflow", inputParameters: [{ prompt }] },
  async () => {
    const response = await llm.create({
      messages: [new UserMessage(prompt)],
    });
    return response.getTextContent();
  },
);

console.log(answer);
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your BeeAI workflow with agent, chat, and tool spans.

## Configuration

| Parameter              | Type                                       | Default              | Description                                                                                                   |
| ---------------------- | ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `api_key` / `apiKey`   | `str \| None` / `string \| undefined`      | `RESPAN_API_KEY`     | Respan API key for trace export.                                                                              |
| `base_url` / `baseURL` | `str \| None` / `string \| undefined`      | `RESPAN_BASE_URL`    | Respan trace export base URL.                                                                                 |
| `instrumentations`     | `list` / `RespanInstrumentation[]`         | `[]`                 | Plugin instrumentations to activate, such as `BeeAIInstrumentor()` or `new BeeAIInstrumentor({ sdkModule })`. |
| `app_name` / `appName` | `str \| None` / `string \| undefined`      | `None` / `undefined` | Service name shown on exported spans.                                                                         |
| `metadata`             | `dict \| None` / `Record<string, unknown>` | `None` / `undefined` | Default metadata attached to exported spans.                                                                  |
| `environment`          | `str \| None` / `string \| undefined`      | `None` / `undefined` | Environment tag, such as `"production"`.                                                                      |

## Attributes

### In Respan()

Set defaults at initialization — these apply to exported spans.

**`Python`**

```python Python
from respan import Respan
from respan_instrumentation_beeai import BeeAIInstrumentor

respan = Respan(
    app_name="beeai-agent-api",
    instrumentations=[BeeAIInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "beeai-api", "version": "1.0.0"},
)
```

**`TypeScript`**

```typescript TypeScript
import * as beeaiFramework from "beeai-framework";
import { Respan } from "@respan/respan";
import { BeeAIInstrumentor } from "@respan/instrumentation-beeai";

const respan = new Respan({
  appName: "beeai-agent-api",
  instrumentations: [new BeeAIInstrumentor({ sdkModule: beeaiFramework })],
});
await respan.initialize();
```

### With propagate_attributes

Override per-request using a context scope.

**`Python`**

```python Python
from respan import Respan, propagate_attributes
from respan_instrumentation_beeai import BeeAIInstrumentor

respan = Respan(instrumentations=[BeeAIInstrumentor()])


async def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = await agent.run(message)
        print(response.last_message.text)
```

**`TypeScript`**

```typescript TypeScript
async function handleRequest(userId: string, message: string) {
  await respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      await respan.withWorkflow({ name: "beeai_user_request.workflow" }, async () => {
        const response = await llm.create({ messages: [new UserMessage(message)] });
        console.log(response.getTextContent());
      });
    },
  );
}
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |