@moklabsio/agentscope-sdk

TypeScript SDK for instrumenting AI agents with AgentScope. Uses OpenTelemetry under the hood for distributed tracing.

Quick Start

npm install @moklabsio/agentscope-sdk

Basic Setup

import { AgentScope } from '@moklabsio/agentscope-sdk';

const scope = AgentScope.init({
  endpoint: 'http://localhost:3001',
  projectId: 'my-project',
});

Auto-Instrument OpenAI and Anthropic Clients

The SDK can patch OpenAI and Anthropic clients to automatically emit LLM spans with model, token usage, and cost — no manual wrapping required.

import { AgentScope, instrumentOpenAI, instrumentAnthropic } from '@moklabsio/agentscope-sdk';
import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';

const scope = AgentScope.init({
  endpoint: 'http://localhost:3001',
  projectId: 'my-project',
});

const openai = new OpenAI();
instrumentOpenAI(openai, scope, { agentName: 'my-agent' });

const anthropic = new Anthropic();
instrumentAnthropic(anthropic, scope, { agentName: 'my-agent' });

// These calls now automatically emit LLM spans
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

Manual Span Wrapping

If you need finer control, use the wrapper methods:

const result = await scope.wrapAgent('my-agent', async () => {
  await scope.wrapTool('web-search', async () => {
    return searchResults;
  });

  return await scope.wrapLLMCall('generate', async () => {
    const res = await llm.complete(prompt);
    return { inputTokens: res.usage.input, outputTokens: res.usage.output };
  }, { model: 'claude-sonnet-4-5-20250514' });
}, { agentTask: 'Answer user question' });

Streaming Support

Both instrumentOpenAI and instrumentAnthropic handle streaming responses. Token counts are collected from the final chunks and the span is ended after the stream completes.

const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

Configuration

| Option | Description | Default | |--------|-------------|---------| | endpoint | OTLP endpoint URL | Required | | projectId | Project identifier | Required | | tenantId | Tenant ID | 'default' | | apiKey | API key for authentication | None | | serviceName | Service name in traces | 'agentscope-sdk' | | debug | Enable debug logging | false |

Cost Tracking

The SDK includes a pricing table for 30+ models. Cost is calculated automatically:

import { calculateCost, MODEL_PRICING } from '@moklabsio/agentscope-sdk';

const cents = calculateCost('gpt-4o', 1000, 500);
console.log(`Cost: $${(cents / 100).toFixed(4)}`);

Supported models: OpenAI (GPT-4.x, o1, o3-mini), Anthropic (Claude 3/4.x), Google (Gemini 1.5/2.x), Meta (Llama 3.x), Mistral, DeepSeek.

Example

A runnable quickstart is included in examples/quickstart.ts:

npx tsx examples/quickstart.ts

Running Tests

npx tsx tests/auto-instrument.test.ts

Shutdown

Always flush pending spans before process exit:

await scope.shutdown();