agentops

library0.4.21pypypiunverified

AgentOps is an observability and DevTool platform for AI agents, providing tools to trace, debug, and deploy reliable AI agents and LLM applications. It offers features like session replays, LLM cost tracking, failure detection, tool usage statistics, and benchmarking, helping engineers move AI agents from prototype to production by ensuring they operate safely, efficiently, and transparently.

llm-agents ai-ml observability devops

pip install agentops python-dotenv

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v0.4.21 · 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.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 7.6s · import 1.630s · 53MB

53MB installed

● package 53MB

Code

Verified usage

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

init

✓ from agentops import init

Initializes the AgentOps SDK for auto-instrumentation.

agent

✓ from agentops.sdk.decorators import agent

Decorator to track agent logic and group downstream operations.

operation

✓ from agentops.sdk.decorators import operation

Decorator to instrument any function as a tracked operation/span.

trace

✓ from agentops.sdk.decorators import trace

Decorator for creating custom traces, especially in multi-threaded environments.

workflow

✓ from agentops.sdk.decorators import workflow

Decorator to track multi-operation workflows.

end_session

✓ from agentops import end_session

Manually ends the current AgentOps session.

This quickstart demonstrates the minimal setup for AgentOps. After installation, initialize AgentOps with your API key (preferably from an environment variable). This enables automatic instrumentation of supported LLM and agent framework calls. Remember to call `load_dotenv()` before `agentops.init()` if you're using a `.env` file.

import agentops import os from dotenv import load_dotenv # Load environment variables (recommended for API keys) load_dotenv() # Initialize AgentOps # The API key can be passed directly or set as an environment variable AGENTOPS_API_KEY # Get your API key from the AgentOps Dashboard (app.agentops.ai) AGENTOPS_API_KEY = os.getenv("AGENTOPS_API_KEY", "") agentops.init(AGENTOPS_API_KEY) print("AgentOps initialized! Any supported LLM or agent framework calls will now be tracked.") # Example with an OpenAI call (if openai is installed and configured) # from openai import OpenAI # client = OpenAI() # completion = client.chat.completions.create( # model="gpt-3.5-turbo", # messages=[ # {"role": "system", "content": "You are a helpful assistant."}, # {"role": "user", "content": "Hello!"} # ] # ) # print(completion.choices.message.content) # It's good practice to explicitly end the session, especially for single-run scripts. agentops.end_session('Success') print("AgentOps session ended.")

agentops --version

Debug

Known issues

breakingThe AgentOps SDK is in active development (0.x versions), and its API surface, internal architecture, and integration points (e.g., AutoGen to AG2 migration in 0.4.19) can evolve rapidly. This may necessitate updates to your code when upgrading versions.

fix

Refer to the official changelog and documentation for each new minor version for specific migration guides and updated integration patterns. Ensure your environment dependencies are compatible with the AgentOps version used.

affects: <1.0.0

gotchaFailing to correctly configure the `AGENTOPS_API_KEY` (either via environment variable or directly in `agentops.init()`) will prevent data from being sent to the AgentOps dashboard. If using a `.env` file, ensure `python-dotenv.load_dotenv()` is called *before* `agentops.init()`.

fix

Set the `AGENTOPS_API_KEY` environment variable (e.g., `export AGENTOPS_API_KEY="your_key"` or in a `.env` file) or pass it directly to `agentops.init(api_key="your_key")`. Always call `load_dotenv()` early in your script if you rely on a `.env` file.

affects: All

gotchaWhile `agentops.init()` provides automatic instrumentation for many popular LLM and agent frameworks, achieving finer-grained control and tracking custom operations, agents, or tools requires explicit use of decorators like `@agent`, `@operation`, `@trace`, and `@tool` from `agentops.sdk.decorators`. Auto-instrumentation provides a good starting point, but detailed insights often need manual tagging.

fix

For deeper visibility into custom agent logic, specific function calls, or multi-step workflows, import and apply the relevant decorators (e.g., `@operation` on functions, `@agent` on agent classes) to your code. Refer to the 'Beyond Automatic Instrumentation: Decorators' section in the documentation.

affects: All

gotchaFor comprehensive and accurate trace recording, especially in single-run scripts or when explicit lifecycle management is desired, explicitly calling `agentops.end_session()` is crucial to mark the completion of an agent's run. While `agentops.init()` can auto-start a session, auto-ending might not always capture the full lifecycle details without explicit calls or decorator usage.

fix

Ensure `agentops.end_session()` is called at the logical end of your agent's execution path. Consider using `try...finally` blocks or the `@trace` decorator for robust session management.

affects: All

gotchaDeploying AI agents introduces unique operational challenges (e.g., non-deterministic behavior, infinite loops, tool hallucinations, agent drift) that extend beyond traditional software or ML monitoring. AgentOps helps address these with observability, but developers must still design agents with robust guardrails, controlled tool access, continuous evaluation, and human oversight in mind for production readiness.

fix

Integrate AgentOps with a broader AgentOps framework that includes robust testing, evaluation harnesses, version control for prompts/configs, and defined policies for agent behavior and tool usage. Use AgentOps metrics to inform these design choices and detect anomalies proactively.

affects: All

Upgrade

Version history

0.4.21latest on PyPI

Audit

Dependencies

python-dotenvoptionalRecommended for managing API keys as environment variables.

langchainoptionalOptional dependency for LangChain integration and advanced features.

llama-indexoptionalOptional dependency for LlamaIndex integration and advanced features.

ag2optionalRequired for AG2 (formerly AutoGen) integration.

Agent activity

86 hits · last 30 days