CoreWeave Forge Python SDK

The Forge Python SDK supports Python 3.10 and newer.

Python agent tracing

The coreweave.forge.agentlens.tracing subpackage sends agent, LLM, tool, and sub-agent spans to the Weave Agents experience over OTLP/HTTP. It does not depend on the full weave or wandb Python packages.

from coreweave.forge.agentlens import tracing

tracing.init("entity/project")  # Reads WANDB_API_KEY.

with tracing.Conversation(agent_name="research-agent") as conversation:
    with conversation.start_turn(user_message="Find the answer") as turn:
        with turn.start_llm(model="gpt-5") as llm:
            llm.output("The answer is 42.")

tracing.shutdown()

OpenAI integration

Install the optional provider dependency, then initialize tracing before making OpenAI calls:

pip install "coreweave[openai]"

from openai import OpenAI
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = OpenAI()

response = client.responses.create(
    model="gpt-5-mini",
    input="Hello",
)

tracing.shutdown()

tracing.init() patches an OpenAI SDK imported before initialization and installs an import hook for one imported later. Set autopatch_integrations=False to opt out, or use tracing.integrations.patch_openai() and tracing.integrations.unpatch_openai() for explicit control. Sync and async Chat Completions, structured-output parsing, Responses, streaming, and image generation retain their native SDK interfaces while AgentLens captures completed output and usage.

The integration records multimodal messages, tool calls, request settings, cached and reasoning tokens, response metadata, and integration provenance. Standalone calls get a synthetic openai SDK turn. The integration supports openai>=1.99.9.

Anthropic integration

Install the optional provider dependency and initialize tracing normally:

pip install "coreweave[anthropic]"

from anthropic import Anthropic
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)

tracing.shutdown()

tracing.init() patches an Anthropic SDK that was imported earlier and installs an import hook for one imported later. Set autopatch_integrations=False to opt out, or use tracing.integrations.patch_anthropic() and tracing.integrations.unpatch_anthropic() for explicit control. Sync and async Messages calls, stream=True, the Messages stream helper, structured output parsing, tool calls, media, request settings, token usage, and prompt-cache usage are traced.

Calls made inside an active AgentLens turn become children of that turn. A standalone provider call gets a synthetic anthropic SDK turn so it remains visible in AgentLens. The integration supports anthropic>=0.18.0.

Google Gen AI integration

Install the optional Gemini provider dependency and initialize tracing before creating or using a Google Gen AI client:

pip install "coreweave[google-genai]"

from google import genai
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = genai.Client()

response = client.models.generate_content(
    model="gemini-flash-latest",
    contents="Hello",
)

tracing.shutdown()

tracing.init() patches an imported google.genai SDK and watches for one imported later. Set autopatch_integrations=False to opt out, or use tracing.integrations.patch_google_genai() and tracing.integrations.unpatch_google_genai() explicitly. Sync and async content generation, streaming, chat helpers, and Imagen generation retain their native interfaces while AgentLens records messages, system instructions, tools, media, request settings, response metadata, token usage, cached input, and thinking tokens.

Standalone calls get a synthetic gemini SDK (or vertex_ai SDK) turn. The integration supports google-genai>=1.0.0,<=1.23.0.

Recorded request settings include temperature, top-k, top-p, frequency and presence penalties, token limits, stop sequences, seed, and candidate count. Imagen's requested image count is recorded as the choice count. Token usage includes Google's reported total when available, including an explicit zero; an omitted total stays omitted.

The start_* factories start spans immediately. You can pair them with end() or the matching end_* function instead of using with; entering a factory-created span as a context manager does not start it twice. Direct Turn, LLM, Tool, and SubAgent construction remains non-emitting until start() or context-manager entry, so these models can also represent batch data.

project_name must include the entity because the tracing package does not call W&B account APIs to discover one. init accepts explicit api_key and base_url arguments. Otherwise it reads WANDB_API_KEY, WF_TRACE_SERVER_URL, and WANDB_BASE_URL, with .netrc as the API-key fallback.

Call tracing.force_flush() before a latency-sensitive process exit. tracing.shutdown() flushes and closes the export worker and is also registered with atexit. Calling tracing.init again reroutes new spans to the new project. The immediately previous session stays open until the next init or shutdown; finish its spans before then to avoid losing them. New children started after reinitialization use the new project even when their parent belongs to the previous one.

The package owns a private TracerProvider. It exports spans created through this package and does not replace the application's global OpenTelemetry provider or export spans created by unrelated instrumentation.

SDK attribution

Every exported span's OTLP resource includes wandb.sdk.name = "forge" to identify Forge SDK traffic separately from regular Weave SDK traffic. wandb.sdk.version records the package version, and wandb.sdk.language is "python". These attributes are independent of the configurable service.name.

Smoke test

The smoke script emits one synthetic agent turn and LLM span. It does not call an LLM provider.

WANDB_API_KEY=<key> \
FORGE_TRACE_PROJECT=<entity/project> \
uv run python examples/tracing_smoke_test.py

The command exits only after the exporter flushes and prints the conversation ID to find in the Weave Agents experience.

Media

OTLP GenAI message attributes support media parts:

• Raw bytes become a base64 blob part.
• A base64 string can be supplied as blob content.
• HTTP, data, and other URIs become uri parts.
• Provider-side file identifiers become file parts.

with turn.start_llm(model="vision-model") as llm:
    llm.attach_media(uri="https://example.test/image.png", modality="image")

Media is included in the JSON value of gen_ai.input.messages. The tracing subpackage does not upload media into the Weave object store. Prefer URIs for large media because inline blobs count toward the OTLP request-size limit.

Content privacy

Set include_content=False on Conversation to omit messages, tool arguments, tool results, reasoning, and media. Spans retain their owning conversation when completed from another thread or context. The tracing subpackage does not perform PII detection or redaction.

Development

Run these commands from python/:

uv sync --locked --group test
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build

License

Copyright 2026 CoreWeave, Inc.

Licensed under the Apache License, Version 2.0.