AgentOps

Warnings

• breaking The 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.
• gotcha Failing 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.
• gotcha While `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.
• gotcha For 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.
• gotcha Deploying 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.

Install

• pip install agentops python-dotenv Install with dotenv (recommended)

Imports

• 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.

Quickstart

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.")