SDK Reference

@argosvix/sdk の API リファレンスです。wrap() で AI クライアントを包むだけで、呼び出しがすべて自動で記録されます。

インストール

npm install @argosvix/sdk <provider-sdk>

<provider-sdk> には openai / @anthropic-ai/sdk / @google/genai / @mistralai/mistralai のいずれかを指定します（複数を併用することもできます）。

wrap(client, options)

AI クライアントのインスタンスを包んで返します。通常の使い方(create の呼び出し、streaming の for-await 消費)では 既存のコードを書き換えずにそのまま導入できます。

OpenAI SDK の高度な API もほぼそのまま使えます: .withResponse()、ストリーミングの .tee() / .toReadableStream() / .controller(abort)は wrap 後も動作します。ストリーミングでこれらを使う場合は stream_options: { include_usage: true } を明示してください(未指定のときは SDK が usage 記録のために include_usage: true を自動注入し、互換ラッパーが返るため、これらのメソッドは付きません)。注意点は 2 つ: .asResponse()(生 Response の直接読み)だけは記録処理と両立しないため非対応です(該当呼び出しのみ wrap 前のクライアントを使ってください)。また記録のためにストリーム全体を読み切るので、受け取ったストリームの消費が遅い場合はレスポンス全体分のメモリを一時的に使います。

import { wrap } from "@argosvix/sdk";
import OpenAI from "openai";

const openai = wrap(new OpenAI(), {
  apiKey: process.env.ARGOSVIX_API_KEY,
  tags: { service: "my-app", env: "prod" },
});

options.apiKey （省略時は記録されません）

ダッシュボードの API キー画面 で発行した argk_... トークンです。環境変数経由で渡してください。型の上では省略できますが、未指定のまま呼び出すとエラーにはならず、記録の送信だけが行われません（LLM 呼び出し自体はそのまま通ります）。「wrap したのに何も記録されない」ときは、まずこの指定漏れを疑ってください。

options.tags （任意）

任意のキーと値のペアで、ダッシュボードでの絞り込みや集計の軸として利用できます。よく使う例は次のとおりです。

tags: {
  service: "my-app",     // 複数サービスを 1 つのダッシュボードで分離
  env: "prod",           // staging と prod を別々に集計
  feature: "summarize",  // 機能別のコストやレイテンシを比較
  userId: "u_xxx",       // ユーザー単位での利用量計測（PII に注意、ハッシュ化を推奨）
}

⚠️ tags にエンドユーザーの個人情報（メールアドレスや氏名など）を含めないでください（利用規約 第 4 条 第 2 項）。

options.sessionId （任意）

同一セッション（会話）に属する呼び出しをまとめるための ID です。指定すると各記録の sessionId に載り、クエリ API でセッション単位の絞り込みに使えます。Python SDK では ArgosvixConfig(session_id="...") として指定します。

const openai = wrap(new OpenAI(), {
  apiKey: process.env.ARGOSVIX_API_KEY,
  sessionId: "sess_2026_07_08_abc",
});

options.captureContent （任意、既定 false）

true にすると、プロンプト本文と応答本文を記録に含めて送信します。非ストリーミングは全 4 プロバイダー、ストリーミングも観測対象の全経路（OpenAI Chat / OpenAI Responses / Anthropic / Gemini / Mistral、TypeScript・Python 共通）で本文を蓄積して記録します（1 呼び出しあたり 256KB まで。超過分は切り捨てて末尾に truncated マーカーが付きます。ストリームが途中で切れた場合も、そこまでの本文が記録されます）。

ℹ️ サーバー側の取り込みには別途、プロンプト本文・応答本文それぞれ 64KB の上限があります。SDK は送信前に本文を自動でこの上限内へ切り詰める（超過分を捨てて末尾に truncated マーカーを付ける）ため、上限を超える本文があっても記録自体は消えません。

応答にツール呼び出し（function calling）が含まれる場合は、ツール名と引数も toolCalls として記録されます（対象は OpenAI の Chat Completions / Responses 経由の呼び出しのみです。引数内の PII は本文と同じ規則でマスキングされます）。

const openai = wrap(new OpenAI(), {
  apiKey: process.env.ARGOSVIX_API_KEY,
  captureContent: true,
});

Python SDK では capture_content=True を指定します。

from argosvix import wrap, ArgosvixConfig

client = wrap(OpenAI(), ArgosvixConfig(
    api_key=os.environ["ARGOSVIX_API_KEY"],
    capture_content=True,
))

動作の前提と安全設計:

• 送信前に必ず PII マスキングが適用されます（メールアドレス・カード番号・電話番号・マイナンバー・IP アドレスを [REDACTED_*] に置換）。
• サーバー側では、Pro プラン以上でダッシュボードの「平文保存」に明示同意している場合のみ本文が AES-256-GCM で暗号化保存されます。同意がない場合、送信された本文は保存されずに破棄されます。
• 保存された本文の閲覧・削除・アクセスログはダッシュボードの「プライバシー・データ」設定から管理できます。詳細は利用規約 第 4 条の 2 を参照してください。

デプロイ済みプロンプトの取得とタグ付け（resolvePrompt / withPrompt）

プロンプト管理でデプロイした本番プロンプトを SDK から取得し、その版で生成した呼び出しに prompt タグ（{name}@v{version}）を自動付与できます。版別の品質・コスト比較の基盤です。

import { resolvePrompt, withPrompt } from "@argosvix/sdk";

const p = await resolvePrompt("support-bot", {
  apiKey: process.env.ARGOSVIX_API_KEY!,
  // label: "production"（既定）
});

await withPrompt(p, async () => {
  // この中の呼び出しに tags.prompt = "support-bot@v3" が自動で付く
  await openai.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "system", content: p.template }],
  });
});

• resolvePrompt は 60 秒の TTL キャッシュを持ち、ネットワーク断・サーバー障害時は 期限切れキャッシュを返して本流を止めません（デプロイが存在しない 404 は例外を投げます）。
• 明示的に tags.prompt を渡した呼び出しでは自動付与より明示指定が優先されます。
• Python SDK では resolve_prompt(name, api_key=...) と with_prompt(p):（コンテキスト マネージャ）が同じ動作をします。

flushClient(client)

短命なランタイム（Cloudflare Workers / AWS Lambda / Vercel Edge など）では、ハンドラーの finally で 必ず await flushClient() を呼んでください。これを忘れると、ランタイムが送信処理を終える前に終了してしまうため、記録がダッシュボードに届きません。

import { wrap, flushClient } from "@argosvix/sdk";

export default {
  async fetch(req, env) {
    // Workers では環境変数は process.env でなく fetch の env 引数から取る
    const client = wrap(new OpenAI({ apiKey: env.OPENAI_API_KEY }), {
      apiKey: env.ARGOSVIX_API_KEY,
    });
    try {
      return await handler(client, req, env);
    } finally {
      await flushClient(client);
    }
  },
};

長命なプロセス（Node.js サーバー / Bun / Deno deploy など）では不要です。TypeScript SDK はバッファが 100 件に達した時点で自動送信するほか、バッファに記録がある間は約 5 秒（flushIntervalMs、既定 5000）のアイドル自動送信も行います（flushClient() でいつでも明示送信できます）。Python SDK は約 5 秒間隔のバックグラウンド送信です。なお wrap() は best-effort 設計で、Argosvix への送信が失敗してもアプリケーションの LLM 呼び出し自体は壊しません。

フレームワーク統合

プロバイダーのクライアントを直接 wrap() する代わりに、フレームワーク経由でモデルを呼び出している場合は、対応する統合を使います。いずれも wrap() と同じ主要項目（TypeScript の 2 統合は TTFT・推論トークンも記録）（プロバイダー、モデル、トークン、コスト、レイテンシ、TTFT、キャッシュトークン、推論トークン）を記録し、プロバイダーを自動判別し、withTrace によるトレース集約も有効です。⚠ 自動判別が効くのは、各社の公式プロバイダーパッケージを使っている場合です（@ai-sdk/xai や @langchain/deepseek など）。OpenAI 互換 API として baseURL だけ差し替えた場合は、フレームワーク側が「openai」と名乗るため、Argosvix も「openai」として記録します（コストは同じ単価表で計算します）。実プロバイダーで記録したい場合は、設定で provider を明示するか、プロバイダーのクライアントを直接 wrap() してください（宛先 URL から判別します）。Vercel AI Gateway 経由の呼び出しは判別できず、記録されません。予算ゲート・ポリシーゲートの呼び出し前チェックが効くのは Vercel AI SDK ミドルウェアのみ です（LangChain.js と LiteLLM のコールバックは記録専用で、ゲートは評価しません。ゲートを効かせたい場合はプロバイダーのクライアントを直接 wrap() してください）。記録はベストエフォートで動作し、モデルの呼び出しを壊すことはありません。

Vercel AI SDK（ai パッケージ）

argosvixMiddleware() は、wrapLanguageModel に渡せるミドルウェア（LanguageModelV2 / V4 互換）を返します。generateText / streamText / generateObject 経由のすべての呼び出し（ツールループや複数ステップのエージェントのために AI SDK が内部で発行する呼び出しを含む）が記録されます。

import { openai } from "@ai-sdk/openai";
import { wrapLanguageModel, generateText } from "ai";
import { argosvixMiddleware, flushClient } from "@argosvix/sdk";

const observed = argosvixMiddleware({ apiKey: process.env.ARGOSVIX_API_KEY });
const model = wrapLanguageModel({ model: openai("gpt-5.5"), middleware: observed });

try {
  await generateText({ model, prompt: "hi" });
} finally {
  await flushClient(observed); // または await observed.flush()
}

それ以外のプロバイダーは呼び出し自体は通りますが、記録されません。config に provider を指定すれば、強制的に対応付けできます。

LangChain.js

argosvixLangChainHandler() はコールバックハンドラーを返します。callbacks（呼び出しごと、またはモデル構築時）に渡すと、LangChain 経由のすべての LLM 呼び出し（チェーンやエージェントを含む）が記録されます。

import { ChatOpenAI } from "@langchain/openai";
import { argosvixLangChainHandler, flushClient } from "@argosvix/sdk";

const handler = argosvixLangChainHandler({ apiKey: process.env.ARGOSVIX_API_KEY });
const model = new ChatOpenAI({ model: "gpt-5.5" });

try {
  await model.invoke("hi", { callbacks: [handler] });
} finally {
  await flushClient(handler); // または await handler.flush()
}

LiteLLM（Python）

ArgosvixLogger は LiteLLM の CustomLogger です。一度登録すれば、LiteLLM 経由のすべての呼び出し（同期・非同期・ストリーミング・失敗）が記録されます。LiteLLM の Python SDK と LiteLLM proxy の両方で使えます。

import litellm
from argosvix.litellm_callback import ArgosvixLogger

logger = ArgosvixLogger()  # 環境変数 ARGOSVIX_API_KEY を読みます

litellm.callbacks = [logger]
litellm.completion(model="gpt-4o", messages=[{"role": "user", "content": "hi"}])

logger.flush()  # 短命なプロセスでは、バッファ済みの記録を今すぐ送信

LiteLLM proxy で使う場合は、config.yaml の隣に custom_callbacks.py を置いてロガーのインスタンスを定義し、litellm_settings.callbacks: custom_callbacks.argosvix_logger で参照します。

コストは LiteLLM 自身が計算した response_cost を優先し（100 以上のプロバイダーに対応）、取れない場合は Argosvix の単価表で計算します。プロバイダーは ingest API の対応語彙に対応付けます（xAI Grok は「xai」、Moonshot Kimi は「moonshot」が 0.5.5 から、DeepSeek は「deepseek」が 0.6.0 から、それぞれ実プロバイダーで記録。Azure OpenAI は従来どおり「openai」）。それ以外のプロバイダーへの呼び出しは通常どおり実行されますが記録されず、黙って捨てる代わりにプロバイダーごとに 1 回だけ警告を出します。省略可能な依存は pip install 'argosvix[litellm]' で入ります。

プロバイダー別の対応メソッド

長文脈の段階単価

一部のモデルは、プロンプトが一定のトークン数に達すると単価が上がります。⚠ 上がるのは 超えた分だけではなく、その呼び出しの全トークンです。SDK はこの規則どおりに計算します。

⚠ 境界は提供元ごとに 1 トークン違います（公式表記の「到達」と「超過」の差）。 キャッシュヒット入力の単価も、段階に入ると段階側の単価が適用されます。

キャッシュトークン数がプロンプトのトークン数を超えて報告された場合は、プロンプト数で 頭打ちにして計算します（提供元の集計値がずれても、金額が過大に出ないようにするため）。

xAI Grok の利用例（Moonshot Kimi も baseURL と API キーを置き換えるだけで同じ書き方）:

import OpenAI from "openai";
import { wrap } from "@argosvix/sdk";

const client = wrap(
  new OpenAI({ apiKey: process.env.XAI_API_KEY, baseURL: "https://api.x.ai/v1" }),
  { apiKey: process.env.ARGOSVIX_API_KEY },
);
// 以降は OpenAI SDK と同じ書き方で grok-4.5 等を呼び出すだけで記録されます

Python SDK でストリームを途中で打ち切る場合の注意: 同期イテレーションの break はその場で記録されますが、async for の break は Python の言語仕様上、即時のクリーンアップを保証しません。確実に記録するには async with で消費するか、打ち切り後に await stream.aclose() を呼んでください。

これら以外のメソッドの呼び出しはそのまま通過します（記録はされませんが、エラーを握りつぶすこともありません）。一覧にないメソッドの記録をご希望の場合は、[email protected] までご連絡ください。

型定義

import type { ArgosvixConfig } from "@argosvix/sdk";

interface ArgosvixConfig {
  /** ダッシュボードで発行した argk_... トークン（未指定なら記録送信は no-op） */
  apiKey?: string;
  /** 任意のキーと値（絞り込み / 集計の軸） */
  tags?: Record<string, string>;
  /**
   * 取り込み先の完全な POST URL（パス込み。既定 https://ingest.argosvix.com/v1/ingest）。
   * SDK はこの URL にそのまま POST し、パスを付け足しません（プロキシ経由やテスト用途。通常は不要）
   */
  endpoint?: string;
}

トラブルシューティング

• ダッシュボードに記録が出ない — flushClient を呼び忘れていないか（短命なランタイムの場合）、ネットワークの到達性、apiKey のタイプミスを確認してください。
• 記録が表示されるまで時間がかかる — 送信はバッチ化されています（TypeScript は 100 件到達時、または記録がバッファにある間の約 5 秒アイドル送信（flushIntervalMs 既定 5000）、または flushClient() 時。Python は約 5 秒間隔）。低頻度の呼び出しでは flushClient() / flush() を呼ぶと即時反映されます。
• コストが 0 と表示される — そのプロバイダーやモデルの料金表がまだ登録されていない可能性があります。[email protected] までご連絡いただければ追加できます。

サポート

[email protected]

最終更新: 2026-07-29