Skip to main content
Get up and running with AI Gateway and Observability in minutes. The following steps show you how to set up both features with one complete example.

Prerequisites

Installation guide

Configure your project to pull from Backbase Artifactory and install bb-ai-sdk 0.1.9.

Quick setup

1. Configure environment variables

Create a .env file with your credentials:
.env
# AI gateway configuration (required)
AI_GATEWAY_API_KEY=your-api-key
AI_GATEWAY_ENDPOINT=your-ai-gateway-endpoint

# Observability configuration (required for tracing)
LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_HOST=https://cloud.langfuse.com
Never commit .env files to version control. Ensure .env is in your .gitignore.

2. Create your first agent

Create agent.py with AI Gateway and Observability:
agent.py
import asyncio
import logging
from bb_ai_sdk.logging import DEFAULT_DATEFMT, STANDARD_FORMAT, init as init_logging
from bb_ai_sdk.observability import configure_observability
from bb_ai_sdk.ai_gateway import AsyncAIGateway

logging.basicConfig(
    level=logging.INFO,
    format=STANDARD_FORMAT,
    datefmt=DEFAULT_DATEFMT,
)
init_logging(capture_warnings=True)

configure_observability(service_name="my-first-agent")


async def main() -> None:
    gateway = AsyncAIGateway.create(
        model_id="gpt-4o",
        agent_id="550e8400-e29b-41d4-a716-446655440000",
    )

    # Automatically traced when the tracer is initialized before gateway creation
    response = await gateway.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello, World!"}],
    )

    print(response.choices[0].message.content)


if __name__ == "__main__":
    asyncio.run(main())

3. Run your agent

source .env
uv run python agent.py
If you see a response, you’ve successfully connected to the AI Gateway! Check your Langfuse dashboard to see the trace.

What happens next?

When you call configure_observability() before creating the gateway, LLM calls through AsyncAIGateway are automatically traced with OpenInference semantics. This integration gives you:
  • AI Gateway: Routes your LLM calls through the Backbase AI Platform with automatic authentication, agent ID validation, and policy enforcement
  • Automatic tracing: Gateway calls appear in Langfuse with tokens, latency, cost, and request/response context when export credentials are set
  • Minimal setup: Call configure_observability() at startup before gateway instances
The sync AIGateway client does not attach OpenAIInstrumentor automatically in the SDK today. For sync scripts, attach OpenAIInstrumentor manually—see Gateway-only script—or use AsyncAIGateway as in the example above.

Customize your setup

  • AI Gateway: Configure streaming, tools, framework adapters, error handling, and advanced client options
  • Observability: Add custom tracing, export to Langfuse, Grafana, or an OTLP endpoint, and tune export settings

Next steps

AI gateway

Learn about streaming, tools, and framework adapters

Observability

Explore custom tracing and advanced configuration

Starter kits

See SDK integrated in production templates

Examples

View complete working examples