# agentops

> TypeScript implementation of the AgentOps SDK

Latest version **0.1.0** (published 2025-06-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install agentops
pnpm add agentops
yarn add agentops
bun add agentops
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2025-06-05 |
| First published | 2023-11-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 10 |
| Unpacked size | 205 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | AgentOps |
| Maintainers | tcdent, reibs |
| Keywords | opentelemetry, instrumentation, genai, agents, observability |

## Links

- npm: https://www.npmjs.com/package/agentops
- Repository: https://github.com/AgentOps-AI/agentops-ts
- Homepage: https://agentops.ai
- Issues: https://github.com/AgentOps-AI/agentops-ts/issues
- npm.io page: https://npm.io/package/agentops

## Dependencies (10)

- [debug](https://npm.io/package/debug.md) ^4.4.1
- [@openai/agents](https://npm.io/package/@openai/agents.md) ^0.0.1
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.8.0
- [@opentelemetry/sdk-node](https://npm.io/package/@opentelemetry/sdk-node.md) ^0.52.1
- [@opentelemetry/resources](https://npm.io/package/@opentelemetry/resources.md) ^1.25.1
- [@opentelemetry/sdk-trace-base](https://npm.io/package/@opentelemetry/sdk-trace-base.md) ^1.25.1
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ^1.25.1
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.52.1
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.25.1
- [@opentelemetry/exporter-trace-otlp-http](https://npm.io/package/@opentelemetry/exporter-trace-otlp-http.md) ^0.52.1

## Recent versions

- 0.1.0 (latest) — 2025-06-05
- 0.0.4 — 2024-01-23
- 0.0.3 — 2023-12-11
- 0.0.2 — 2023-11-30

## README

# AgentOps TypeScript SDK

<div align="center">
  <a href="https://agentops.ai?ref=gh">
    <img src="docs/images/logo/github-banner.png" alt="Logo">
  </a>
</div>

<div align="center">
  <em>Observability and DevTool platform for AI Agents</em>
</div>

<br />

<div align="center">
  <a href="https://github.com/agentops-ai/agentops/issues">
  <img src="https://img.shields.io/github/commit-activity/m/agentops-ai/agentops-ts" alt="git commit activity">
  </a>
  <img src="https://img.shields.io/pypi/v/agentops?&color=3670A0" alt="PyPI - Version">
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg?&color=3670A0" alt="License: MIT">
  </a>
</div>

<p align="center">
  <a href="https://twitter.com/agentopsai/">
    <img src="https://img.shields.io/twitter/follow/agentopsai?style=social" alt="Twitter" style="height: 20px;">
  </a>
  <a href="https://discord.gg/FagdcwwXRR">
    <img src="https://img.shields.io/badge/discord-7289da.svg?style=flat-square&logo=discord" alt="Discord" style="height: 20px;">
  </a>
  <a href="https://app.agentops.ai/?ref=gh">
    <img src="https://img.shields.io/badge/Dashboard-blue.svg?style=flat-square" alt="Dashboard" style="height: 20px;">
  </a>
  <a href="https://docs.agentops.ai/introduction">
    <img src="https://img.shields.io/badge/Documentation-orange.svg?style=flat-square" alt="Documentation" style="height: 20px;">
  </a>
  <a href="https://entelligence.ai/AgentOps-AI&agentops">
    <img src="https://img.shields.io/badge/Chat%20with%20Docs-green.svg?style=flat-square" alt="Chat with Docs" style="height: 20px;">
  </a>
</p>

A TypeScript implementation of the AgentOps SDK that exports GenAI conventional OpenTelemetry data to standards-compliant OTel collectors. This SDK provides automatic instrumentation for multiple agent frameworks and AI libraries.

<div align="center">
  <video src="https://github.com/user-attachments/assets/dfb4fa8d-d8c4-4965-9ff6-5b8514c1c22f" width="650" autoplay loop muted></video>
</div>

## Features

- 🔌 **Plugin Architecture**: Dynamic loading and configuration of instrumentors
- 🤖 **GenAI Support**: Built-in support for OpenTelemetry GenAI semantic conventions
- 📊 **Standards Compliant**: Exports to any OpenTelemetry-compatible collector
- 🛠️ **Framework Agnostic**: Instrument multiple agent frameworks simultaneously
- 🔧 **TypeScript First**: Full TypeScript support with comprehensive type definitions
- 💸 **LLM Cost Management**: Track spend with LLM foundation model providers
- 🧪 **Agent Benchmarking**: Test your agents against 1,000+ evals
- 🔐 **Compliance and Security**: Detect common prompt injection and data exfiltration exploits

## Installation

```bash
npm install agentops
```

## Quick Start

### 1. Set your API key (recommended)

```bash
export AGENTOPS_API_KEY=your-api-key
```

### 2. Initialize the SDK

```typescript
import { agentops } from 'agentops';

await agentops.init();

// Your AI agent code here - instrumentation happens automatically!
```

### Alternative: Pass API key explicitly

```typescript
import { agentops } from 'agentops';

await agentops.init({
  apiKey: 'your-api-key'
});
```

## Building

To build the project from source:

```bash
npm install
npm run build
```

This will compile the TypeScript source code to JavaScript in the `dist/` directory.

## Running the Example

The repository includes an OpenAI Agents example that demonstrates the SDK in action:

1. First, create a `.env` file in the `examples/openai-agents-example` directory:

```bash
cd examples/openai-agents-example
cat > .env << EOF
AGENTOPS_API_KEY=your-agentops-api-key
OPENAI_API_KEY=your-openai-api-key
EOF
```

2. Then run the example:

```bash
npm install
npm run dev
```

The example will:
1. Initialize AgentOps instrumentation
2. Create a weather assistant agent with tool calling capabilities
3. Execute a sample query
4. Export telemetry data to the AgentOps platform

## OpenAI Agents Support

AgentOps provides first-class support for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-js/), automatically instrumenting:

- **Agent Lifecycle**: Track agent creation, execution, and completion
- **LLM Generation**: Capture model requests, responses, and token usage
- **Function Calls**: Monitor tool usage and function execution
- **Audio Processing**: Observe speech-to-text and text-to-speech operations
- **Handoffs**: Track agent-to-agent communication and workflow transitions
- **Custom Events**: Capture domain-specific agent behaviors

### Automatic Instrumentation

Simply initialize AgentOps before using the OpenAI Agents SDK:

```typescript
import { agentops } from 'agentops';
import { Agent, run } from '@openai/agents';

// Initialize AgentOps first
await agentops.init();

// Create your agent with tools and instructions
const agent = new Agent({
  name: 'My Assistant',
  instructions: 'You are a helpful assistant.',
  tools: [/* your tools */],
});

// Run the agent - instrumentation happens automatically
const result = await run(agent, "Hello, how can you help me?");
console.log(result.finalOutput);
```

All agent interactions will be automatically captured and exported to your AgentOps dashboard with full OpenTelemetry semantic conventions.

## Debug Logging

To see detailed instrumentation and tracing logs:

```bash
DEBUG=agentops:* node your-app.js
```

## Why AgentOps? 🤔

Without the right tools, AI agents are slow, expensive, and unreliable. Our mission is to bring your agent from prototype to production. Here's why AgentOps stands out:

- **Comprehensive Observability**: Track your AI agents' performance, user interactions, and API usage.
- **Real-Time Monitoring**: Get instant insights with session replays, metrics, and live monitoring tools.
- **Cost Control**: Monitor and manage your spend on LLM and API calls.
- **Failure Detection**: Quickly identify and respond to agent failures and multi-agent interaction issues.
- **Tool Usage Statistics**: Understand how your agents utilize external tools with detailed analytics.
- **Session-Wide Metrics**: Gain a holistic view of your agents' sessions with comprehensive statistics.

AgentOps is designed to make agent observability, testing, and monitoring easy.

## Star History

Check out our growth in the community:

<img src="https://api.star-history.com/svg?repos=AgentOps-AI/agentops&type=Date" style="max-width: 500px" width="50%" alt="Logo">

---
_Source: https://npm.io/package/agentops · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._