BeeAI (tracing) | Respan Docs

BeeAI 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 and grab an API key.

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

Use Respan Gateway

See BeeAI gateway setup to route this integration through the Respan gateway.

Example projects

Example project repository

Setup

Install packages

pip install respan-ai respan-instrumentation-beeai beeai-framework

@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

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

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

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())

View your trace

Open the Traces page 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.

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"},
)

With propagate_attributes

Override per-request using a context scope.

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)

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.