Registry / llm-agents / langwatch

langwatch

JSON →
library0.26.0pypypi✓ verified 85d ago

LangWatch is a Python SDK for monitoring, evaluating, and testing LLM-powered applications and AI agents. It provides end-to-end observability by capturing traces and spans for LLM calls, RAG retrievals, and other pipeline steps, helping developers debug, prevent regressions, and optimize their AI systems. The current version is 0.18.0, and the library undergoes active development with regular releases.

pip install langwatch
INSTALL
IMPORT
SIG · LANGWATCH
L
langwatch
llm-agentspythonv0.26.0
Install
15.1s avg
Import
4062ms
Disk
194MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.26.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 4.306s · 100.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 15.1s · import 3.818s · 101MB
194MB installed
● package 194MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

langwatch
import langwatch
setup
langwatch.setup()
Initializes the LangWatch client.
trace
@langwatch.trace()
Decorator to capture an end-to-end operation as a trace.
span
@langwatch.span()
Decorator to instrument specific parts of a pipeline within a trace.
OpenAIInstrumentor
from langwatch.instrumentors import OpenAIInstrumentor
from langwatch import OpenAIInstrumentor
Instrumentors are typically found in the `langwatch.instrumentors` submodule.
LangChainTracer
import langwatch.langchain langWatchCallback = langwatch.langchain.LangChainTracer()
from langwatch import LangChainTracer
LangChain integration is via `langwatch.langchain` submodule and uses a context manager or callback.

This quickstart demonstrates how to initialize LangWatch, enable automatic OpenAI instrumentation, and trace an asynchronous function that interacts with the OpenAI API. It highlights the use of `langwatch.setup()` and the `@langwatch.trace()` decorator, along with handling the `LANGWATCH_API_KEY`.

import os import langwatch from langwatch.instrumentors import OpenAIInstrumentor from openai import OpenAI # Ensure your API key is set as an environment variable or pass it directly # os.environ["LANGWATCH_API_KEY"] = "YOUR_LANGWATCH_API_KEY" api_key = os.environ.get("LANGWATCH_API_KEY", "") if not api_key: print("Warning: LANGWATCH_API_KEY environment variable not set. Traces will not be sent.") # For demonstration, we'll proceed but you should set your key. # In a real application, you might raise an error or configure LangWatch to only log locally. # Initialize LangWatch early in your application # Automatically instruments OpenAI calls within the decorated functions langwatch.setup( api_key=api_key, instrumentors=[OpenAIInstrumentor()] ) client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", "")) # Assume OpenAI API key is also set @langwatch.trace(name="UserInteraction") async def handle_user_query(query: str): print(f"Processing query: {query}") try: response = client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": query} ] ) result = response.choices[0].message.content print(f"Assistant's response: {result}") return result except Exception as e: langwatch.get_current_trace().error(str(e)) # Record error if something goes wrong print(f"An error occurred: {e}") raise async def main(): await handle_user_query("Tell me a fun fact about Python.") # Ensure traces are flushed before the application exits await langwatch.shutdown() import asyncio asyncio.run(main())
langwatch --version
Debug
Known issues
gotchaTraces might not appear in the LangWatch dashboard if the `LANGWATCH_API_KEY` environment variable is not set or passed explicitly during `langwatch.setup()`.
fix
Set `LANGWATCH_API_KEY=your_api_key` in your environment variables or provide it as `api_key='your_api_key'` to `langwatch.setup()`.
affects: All versions
gotchaIn applications that exit quickly (e.g., short scripts), traces might not be fully sent to the LangWatch backend before termination.
fix
Ensure `await langwatch.shutdown()` is called before your application exits to flush any pending traces.
affects: All versions
gotchaLangWatch uses OpenTelemetry under the hood. Incorrect or conflicting OpenTelemetry configurations can interfere with LangWatch's tracing.
fix
Consult the LangWatch documentation on OpenTelemetry integration if you have an existing OpenTelemetry setup. Ensure compatible versions and proper exporter configuration.
affects: All versions
gotchaThe `langwatch` Python SDK is distinct from the `langwatch-scenario` library, which focuses on agent simulations.
fix
Install `langwatch-scenario` separately if you intend to use the simulation framework (`pip install langwatch-scenario`). Be aware that their functionalities are complementary but distinct.
affects: All versions
Errors
Common errors & fixes
No traces appearing in LangWatch dashboard.
The `LANGWATCH_API_KEY` environment variable is likely not set, or the API key passed to `langwatch.setup()` is incorrect or missing.
fix
Set your LangWatch API key as an environment variable: `export LANGWATCH_API_KEY="your_api_key"` (Linux/macOS) or `$Env:LANGWATCH_API_KEY="your_api_key"` (PowerShell), or pass it directly: `langwatch.setup(api_key="your_api_key")`.
ImportError: cannot import name 'OpenAIInstrumentor' from 'langwatch'
Specific modules like instrumentors are located within subpackages, not directly under the top-level `langwatch` package.
fix
Import the symbol from its correct submodule path, e.g., `from langwatch.instrumentors import OpenAIInstrumentor`.
Error: Trace not found for current context.
Attempting to call `langwatch.get_current_trace().error()` or similar trace-specific methods outside of an active trace context (i.e., not within a `@langwatch.trace()` or `@langwatch.span()` decorated function/context block).
fix
Ensure all operations that interact with the current trace are performed within a function or block that is decorated with `@langwatch.trace()` or `@langwatch.span()`.
Upgrade
Version history
0.26.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
openaioptionalCommonly used with LangWatch for LLM instrumentation, as shown in quickstart examples.
langchainoptionalUsed for automatic instrumentation of LangChain applications.
langwatch-scenariooptionalA separate but related library for agent testing simulations.
Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
2
Resources