Maxim AI

Integrate Maxim SDK for comprehensive LLM observability, tracing, and evaluation.

Overview

Bifrost provides comprehensive LLM observability through the Maxim plugin, enabling seamless tracking, evaluation, and analysis of AI interactions. The plugin automatically forwards all LLM requests and responses to Maxim’s platform for detailed monitoring and performance insights.

---

Setup

The Maxim plugin enables seamless observability and evaluation of LLM interactions by forwarding inputs/outputs to Maxim’s platform:

Go SDK

package main

import (
    "context"
    bifrost "github.com/maximhq/bifrost/core"
    "github.com/maximhq/bifrost/core/schemas"
    maxim "github.com/maximhq/bifrost/plugins/maxim"
)

func main() {
    // Initialize Maxim plugin
    maximPlugin, err := maxim.Init(maxim.Config{
        ApiKey:    "your_maxim_api_key",
        LogRepoId: "your_default_repo_id", // Optional: fallback repository
    })
    if err != nil {
        panic(err)
    }

    // Initialize Bifrost with the plugin
    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
        Account: &yourAccount,
        LLMPlugins: []schemas.LLMPlugin{maximPlugin},
    })
    if err != nil {
        panic(err)
    }
    defer client.Shutdown()

    // All requests will now be traced to Maxim
}

config.json

For HTTP transport, configure via environment variables:

{
  "plugins": [
    {
      "enabled": true,
      "name": "maxim",
      "config": {        
        "api_key": "your_maxim_api_key",
        "log_repo_id": "your_default_repo_id"
      }
    }
  ]
}

Configuration

Field	Type	Required	Description
ApiKey	string	✅ Yes	Your Maxim API key for authentication
LogRepoId	string	❌ No	Default log repository ID (can be overridden per request)

Repository Selection

The plugin uses repository selection with the following priority:

1. Header/Context Repository - Highest priority
2. Default Repository (from plugin config) - Fallback
3. Skip Logging - If neither is available

Go SDK

ctx := context.Background()

// Use specific repository for this request
ctx = context.WithValue(ctx, maxim.LogRepoIDKey, "project-specific-repo")

Gateway

# Use default repository (from config)
curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "gpt-4", "messages": [...]}'

# Override with specific repository
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-maxim-log-repo-id: project-specific-repo" \
  -d '{"model": "gpt-4", "messages": [...]}'

Custom Trace Management

Trace Propagation

The plugin supports custom session, trace, and generation IDs for advanced tracing scenarios:

Go SDK

ctx := context.Background()

// Prefer typed keys from the Maxim plugin
ctx = context.WithValue(ctx, maxim.TraceIDKey, "custom-trace-123")
ctx = context.WithValue(ctx, maxim.GenerationIDKey, "custom-gen-456")
ctx = context.WithValue(ctx, maxim.SessionIDKey, "user-session-789")

// Optionally set human-friendly names
ctx = context.WithValue(ctx, maxim.TraceNameKey, "checkout-flow")
ctx = context.WithValue(ctx, maxim.GenerationNameKey, "rerank-step")

Gateway

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-maxim-trace-id: custom-trace-123" \
  -H "x-bf-maxim-generation-id: custom-gen-456" \
  -H "x-bf-maxim-session-id: user-session-789" \
  -H "x-bf-maxim-trace-name: checkout-flow" \
  -H "x-bf-maxim-generation-name: rerank-step" \
  -d '{"model": "gpt-4", "messages": [...]}'

Custom Tags

You can add custom tags to traces for enhanced filtering and analytics:

Go SDK

ctx := context.Background()

// Pass arbitrary tag key-values via context map
tags := map[string]string{
    "environment":  "production",
    "user-id":      "user-123",
    "feature-flag": "new-ui",
}
ctx = context.WithValue(ctx, maxim.TagsKey, tags)

Gateway

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-maxim-environment: production" \
  -H "x-bf-maxim-user-id: user-123" \
  -H "x-bf-maxim-feature-flag: new-ui" \
  -d '{"model": "gpt-4", "messages": [...]}'

Reserved keys are session-id, trace-id, trace-name, generation-id, generation-name, log-repo-id. All other x-bf-maxim-* headers are treated as tags.

Shared observability dimensions

For tags that should be visible beyond Maxim, use x-bf-dim-* instead of x-bf-maxim-*.

x-bf-dim-* is the canonical per-request dimension prefix in Bifrost. Those dimensions are forwarded to Maxim as tags at lower priority than explicit x-bf-maxim-* tags, and they are also propagated to internal logs, OpenTelemetry spans, Datadog spans, and Prometheus custom labels.

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-dim-environment: production" \
  -H "x-bf-dim-team: platform" \
  -d '{"model": "gpt-4", "messages": [...]}'

If you send both x-bf-dim-environment and x-bf-maxim-environment, Maxim uses the explicit x-bf-maxim-* tag value while the shared dimension still flows to the other observability backends.

Supported Request Types

The plugin supports the following Bifrost request types:

• Text Completion
• Chat Completion
• Agent Gateway operations

Agent Gateway

A2A operations use the same Maxim SDK logger and repository configuration as LLM exports, including the x-bf-maxim-log-repo-id override. Each completed gateway trace becomes a Maxim trace with an operation span. Available operation, agent, task, conversation, push-delivery, and governance identifiers are tags. Errors and streaming updates appear beneath the operation span.

Structured messages, returned tasks, artifacts, and accumulated output populate the trace input and output, with operation content also available in span metadata. Virtual-key content suppression removes those bodies while preserving operation metadata. Raw HTTP capture is not exported to Maxim.

The gateway’s original start and end times are metadata, and each operation span has a duration_ms metric. Maxim’s displayed SDK timeline uses SDK logging time; it does not reconstruct the original gateway timeline from those metadata fields.

See Agent Gateway observability for operation coverage and correlation.

---

Monitoring & Analytics

Once configured, monitor your AI apps in the Maxim Dashboard. Maxim is an end-to-end evaluation & observability platform built to help teams ship AI agents faster while maintaining high quality.

• Experiment / Prompt Engineering Playground++ for prompt design: versioning, comparison (A/B), visual chaining, low-code tooling.

• Simulation & Evaluation Test agents over thousands of scenarios, both automated (statistical, programmatic) and human-in-the-loop for edge cases. Custom and off-the-shelf evaluators.

• Observability / Monitoring Real-time traces, logging, debugging of multi-agent workflows, live issue tracking, alerts when quality or performance degrade.

• Data Engine & Dataset Management Support for multi-modal datasets, import & continuous curation, feedback/annotation pipelines, data splitting for experiments.

• Governance, Security & Compliance Features like SOC 2 Type II compliance, enterprise security controls, permissions, auditability.

• Alerts & SLAs: Threshold-based notifications to keep quality and latency in guardrails

Next Steps

Now that you have observability set up with the Maxim plugin, explore these related topics:

• Tracing - Deep-dive into request/response logging and correlation
• Telemetry - Prometheus metrics, dashboards, and alerting
• Governance - Virtual keys, per-team controls, and usage limits