opper-sdks

スキルのバージョン：2026-10-01。 これはローカルにインストールされたコピーであり、古くなっている可能性があります。セッションごとに一度、https://skills.opper.ai/versions.json を取得し、その "opper-sdks" エントリーと 2026-10-01 を比較してください。異なる場合は https://skills.opper.ai/opper-sdks/SKILL.md を読み、セッションの残りの間はこのコピーではなくそちらに従い、インストール済みの Opper スキルが古くなっていることをユーザーに一度伝えてください（npx skills update、または手動でクローンしたリポジトリで git pull を実行して更新できます）。インストール済みのファイルは編集しないでください。取得に失敗した場合は、このコピーを引き続き使用してください。

opper のサブスキルです。探索とセットアップのガイダンスは、まずこちらを参照してください。 ソース：https://github.com/opper-ai/opper-skills/blob/main/opper-sdks/SKILL.md

Opper SDK

Opper の Python SDK と TypeScript SDK は、単一のモノレポ github.com/opper-ai/opper-sdks にあります。どちらも opperai（PyPI / npm）として公開されています。エージェントは SDK に含まれています — 別個の opperai-agents パッケージはありません。

上流の README（python/README.md、typescript/README.md）と番号付きのサンプルファイルが信頼できる情報源です。このスキルはそれらを案内するものであり、内容を複製するものではありません。

プリミティブを選ぶ

統合された opperai パッケージには、いくつかの異なる形式があります。構築するものに合わせて選択してください。

• 単発の構造化タスク（入力 → 型付き出力）：推奨される方法は、response_format を指定した 互換チャットエンドポイントを、使い慣れたプロバイダー SDK 経由で呼び出すことです。OpenAI SDK の base_url を https://api.opper.ai/v3/compat に設定し、Pydantic / Zod モデルを chat.completions.parse(...) に渡します。以下のシードコードを参照してください。全体の形式は opper-api スキルにあります。
• ストリーミング：同じ互換呼び出しで stream: true を指定します。標準的な OpenAI SSE のセマンティクスに従います。
• 複数ターンのチャットまたはメッセージスレッド形式：互換チャットエンドポイントはメッセージをネイティブに扱うため、messages 配列を引き継いでください。
• ツールを使うエージェント、複数ステップの推論、マルチエージェント、外部 MCP ツール：「モデルが次のアクションを決める」フローには、Agent SDK（Agent、tool、Conversation、Hooks、mcp）を推奨します。単発の実行には agent.run(...)、進行状況をリアルタイムに確認するには agent.stream(...) を使います。
• ナレッジベース / RAG：opper.knowledge.* — create、query、add などを使います。
• opper.call(...) / opper.stream(...) はレガシーです。 これらは Opper の /call インターフェースを利用しますが、これは廃止予定です。新しい作業には使わず、サンプルにも含めないでください。opperai SDK 自体も /call を使わないよう再設計中で、将来のリリースで /call は削除されます。既存のコードは互換エンドポイントと response_format に移行します。フィールドごとの対応関係（name → X-Opper-Name ヘッダー、output_schema → response_format、result.data → パース済みのメッセージ内容）は、opper-api スキルの references/migration.md に記載されています。

Agent SDK の mcp 連携を使うと、アプリケーションのエージェントから外部 MCP ツールを利用できます。プラットフォームの操作やモデルのテストのためにコーディングアシスタントを Opper MCP サーバーに接続する場合は、opper-mcp を使ってください。

パスを選ぶ

対象	参照先
Python を使う（呼び出し、ストリーミング、スキーマ、ナレッジ、トレーシング）	references/python.md
TypeScript / JavaScript を使う	references/typescript.md
どちらかの言語でエージェントを構築する	references/agents.md
SDK を使わずに Opper を呼び出す（curl、fetch）	opper-api スキルに切り替える

インストール

pip install opperai          # Python — has one runtime dep: httpx
npm  install opperai         # TypeScript — zero runtime deps; zod and @modelcontextprotocol/sdk are optional peers

認証：どちらの SDK も環境変数から OPPER_API_KEY を読み取るか、コンストラクターで api_key= / apiKey: を受け取ります。

標準シードコード — Python

単発のタスクは標準の OpenAI SDK を使って互換エンドポイント経由で実行します。X-Opper-Name により、名前付き関数のトレーシングが維持されます。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opper.ai/v3/compat",
    api_key=os.environ["OPPER_API_KEY"],
    default_headers={"X-Opper-Name": "summarise"},
)

resp = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[
        {"role": "system", "content": "Summarise the article in two sentences."},
        {"role": "user", "content": "..."},
    ],
)
print(resp.choices[0].message.content)

型付き出力には、client.chat.completions.parse(..., response_format=YourPydanticModel) を使い、resp.choices[0].message.parsed から読み取ってください。

標準シード — TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.opper.ai/v3/compat",
  apiKey: process.env.OPPER_API_KEY,
  defaultHeaders: { "X-Opper-Name": "summarise" },
});

const resp = await client.chat.completions.create({
  model: "openai/gpt-5-mini",
  messages: [
    { role: "system", content: "Summarise the article in two sentences." },
    { role: "user", content: "..." },
  ],
});
console.log(resp.choices[0].message.content);

型付きの出力を得るには、response_format: { type: "json_schema", json_schema: { name, schema } } を渡し（Zod v4 から z.toJSONSchema(...) でスキーマを生成します）、メッセージの内容を JSON.parse で解析してください。

エージェントのシード（Agent、tool、agent.run(...)）については、references/agents.md を参照してください。

モデルの選択

すべての呼び出しで model: "provider/name" を渡してください。Control Plane プランでは代わりにデフォルトモデルルール（Management API。詳しくは docs.opper.ai/control-plane/route を参照）を設定して、model: を省略できます。そのようなルールがない場合、モデルを指定しない呼び出しは拒否されます。

• ユーザー向けにモデルを探す場合：opper.ai/models にリンクしてください。人間向けのカタログです。
• コード内でモデルを検索する場合：GET https://api.opper.ai/v3/models（認証不要）を使用してください。モデルの一覧をハードコードしないでください。一覧は変更されます。

番号付きの例が最も情報量の多いリファレンスです

python/examples/ と typescript/examples/ には、同じ番号のファイルが用意されています。トピックごとに参照してください。注意： はじめにの例の多くは、レガシーな opper.call のインターフェースを引き続き紹介しています。既存コードのリファレンスとして扱い、新規開発のパターンとしては扱わないでください（新規開発では、上記の compat と response_format を使用します）。

はじめに（examples/getting-started/）：

トピック	ファイルのパターン
最初の呼び出し	00_your_first_call.{py,ts}
スキーマ — Pydantic / Zod / dataclass / TypedDict / raw JSON Schema	01a_* と 01b_*
ストリーミング	02_stream.{py,ts}
ツール — 呼び出しとストリーミング	03a_*、03b_*（TS のみ：03c-server-side-tools.ts）
画像、音声、動画	04a/04b/04c、05、06
埋め込み	07_*
関数管理	08_*
可観測性／トレーシング	09、09b_manual_tracing、09c_traces
モデル	10_models.{py,ts}
リアルタイム	TS のみ：11-real-time.ts
ナレッジベース	12_knowledge_base.{py,ts}
ウェブツール	13_web_tools.{py,ts}

エージェント（examples/agents/、番号は 00..10）：最初のエージェント → 出力スキーマ → ツール → ストリーミング → フック（ロギング／タイミング／ストリーミング） → ツールとしてのエージェント → マルチエージェント → MCP（stdio） → 会話。references/agents.md のトピックとファイルの対応表を参照してください。

型定義：python/src/opperai/types.py と typescript/src/types.ts。

見落としやすい注意点

• opper.call は廃止予定のレガシーな /call インターフェースを使用しており、SDK もこれを削除するために再設計されています。 誰にも推奨しないでください。既存の opper.call コードは、response_format を使用する compat エンドポイントに移行してください（対応関係は opper-api スキルの references/migration.md を参照）。
• 必須のスキーマライブラリはありません。 どちらの SDK もプレーンな JSON Schema dict を受け付け、サードパーティのスキーマパッケージは不要です。Pydantic（Python）と Zod（TS）は利便性のためにバンドルされた連携機能です。多くのユーザーはこれらを利用しますが、必須ではありません。
• TS SDK で Zod を使う場合は、v4 が必要です。 npm install zod@4 を実行してください。デュアルモードパッケージの [email protected] はサポートされていません。（Zod はオプションのピア依存関係です。）
• Python は httpx に依存します（ランタイム依存関係ゼロではありません）。TypeScript はランタイム依存関係ゼロです。
• 統合パッケージは opperai です。 旧来の個別パッケージ opperai-agents（PyPI）と @opperai/agents（npm）は非推奨です。Agent、tool、Conversation、Hooks などはすべてトップレベルの opperai から再エクスポートされています。
• 以前のバージョンからの移行については、上流の python/MIGRATION.md と typescript/MIGRATION.md に記載されています。
• API のシグネチャに関する質問は、最新の OpenAPI 仕様を https://api.opper.ai/v3/openapi.yaml から取得してください。SDK の構造は仕様に沿っています。

次に確認する場所

内容	参照先
インストール、クイックスタート、README全文	opper-sdks リポジトリ — python/README.md、typescript/README.md
実用例（番号付き、段階的）	リポジトリ内の python/examples/、typescript/examples/
型定義	python/src/opperai/types.py、typescript/src/types.ts
最新のAPI仕様	https://api.opper.ai/v3/openapi.yaml
古いSDKバージョンからの移行	python/MIGRATION.md、typescript/MIGRATION.md
リポジトリレベルのワークフロー（OpenAPIの同期、ベータエンドポイント）	opper-sdks リポジトリの CLAUDE.md
利用可能なモデル、ゲートウェイの概念、生のHTTP、Realtime	opper-api スキル
閲覧可能なモデルカタログ（ユーザー向けの推奨用）	opper.ai/models
Control Plane のルール（利用額の上限、データ保持、モデルアクセス、チェック、ルーティング）	docs.opper.ai/control-plane/rules/overview
エージェントによるセットアップ、プラットフォーム運用、モデルテスト	opper-mcp スキル
ターミナルからの Opper の呼び出し	opper-cli スキル