SDK Reference

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

インストール

npm install @argosvix/sdk@alpha <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 を明示してください(未指定のときは usage 記録のための互換ラッパーが返り、これらのメソッドは付きません)。注意点は 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_... トークンです。環境変数経由で渡してください。

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 では 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 マーカーが付きます。ストリームが途中で切れた場合も、そこまでの本文が記録されます）。

応答にツール呼び出し（function calling）が含まれる場合は、ツール名と引数も toolCalls として記録されます（引数内の 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";

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

export default {
  async fetch(req, env) {
    try {
      return await handler(client, req, env);
    } finally {
      await flushClient(client);
    }
  },
};

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

フレームワーク統合

プロバイダーのクライアントを直接 wrap() する代わりに、フレームワーク経由でモデルを呼び出している場合は、対応する統合を使います。どちらも wrap() と同じ項目（プロバイダー、モデル、トークン、コスト、レイテンシ、TTFT、キャッシュトークン、推論トークン）を記録し、同じ 4 つのプロバイダー（OpenAI / Anthropic / Google Gemini / Mistral）に対応し、予算ゲートやポリシーゲート、withTrace によるトレース集約も有効です。記録はベストエフォートで動作し、モデルの呼び出しを壊すことはありません。

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()
}

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

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

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

型定義

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

interface ArgosvixConfig {
  /** ダッシュボードで発行した argk_... トークン */
  apiKey: string;
  /** 任意のキーと値（絞り込み / 集計の軸） */
  tags?: Record<string, string>;
  /** カスタムベース URL（プロキシ経由やテスト用途。通常は不要） */
  endpoint?: string;
}

トラブルシューティング

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

サポート

hello@argosvix.com

最終更新: 2026-07-09