how-tos

コーディングエージェント向けGPT-6.2 API:関数ツール、ストリーミング、長いコンテキスト、キャッシュ

Poyo.ai Team
4 min read
Share:

コーディングエージェントのループを動かすGPT-6.2 API

GPT-6.2 APIは、エージェント用途でOpenAIが現在推しているモデルです。API changelogは、gpt-6.2-sol を「日常的なコーディングやエージェントのワークフロー」に、gpt-6.2-astra を「要求の厳しい推論やコーディングのタスク」に推奨しています。このガイドでは、どちらのモデルもPoYoのResponsesエンドポイント経由でコーディングエージェントに組み込みます。関数ツール、上限付きのループ、進捗のストリーミング、大きなリポジトリのコンテキスト、そして長いセッションの費用を抑えるキャッシュまで扱います。まずはGPT-6.2 Solのモデルページから始め、GPT-6.2 Astraはエスカレーション用に取っておきましょう。

まだ最初のリクエストを送っていない場合は、GPT-6.2 APIガイドから始めてください。

APIがコーディングエージェントに提供するもの

項目PoYoのGPT-6.2
モデルIDgpt-6.2-sol(デフォルト)、gpt-6.2-astra(エスカレーション用)
エージェント用エンドポイントPOST https://api.poyo.ai/v1/responses(OpenAI SDK、base_url="https://api.poyo.ai/v1")
ツール呼び出しResponsesのみ。OpenAI:「ツール呼び出しにはResponsesが必要」
コンテキスト / 最大入力 / 最大出力1,050,000 / 922,000 / 128,000トークン
ストリーミング"stream": true。response.completed が最終出力と usage を運ぶ
推論reasoning.effort。none は拒否される。medium から開始
100万あたりの価格(Sol)入力$1.60 / 出力$8 / キャッシュ読み取り$0.08 / キャッシュ書き込み$2
100万あたりの価格(Astra)入力$6.40 / 出力$32 / キャッシュ読み取り$0.32 / キャッシュ書き込み$8
エラー400 無効なフィールド、401 不正なキー、402 クレジット不足、404 不明なモデル。429 / 5xx はバックオフで再試行

PoYoのResponsesリファレンスには、tools、tool_choice、parallel_tool_calls、reasoning、include、store、previous_response_id、truncation が記載されており、ツールのサポートはモデルによって異なるとされています。OpenAIのモデルページには、GPT-6.2の関数呼び出しと一連のホスト型ツールが記載されています。PoYoのドキュメントにホスト型ツールの例として載っているのは web_search_preview だけなので、このエージェントでは、最初から最後まで自分で制御できる独自の関数ツールを使います。

関数ツールを定義する

ツールのセットは小さく安全に保ちます。モデルが要求できるのは、自分で実装したアクションだけです。

import json, os, subprocess
from pathlib import Path
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])
REPO = Path("/srv/checkout").resolve()

TOOLS = [
    {"type": "function", "name": "read_file",
     "description": "Read a UTF-8 text file from the repository.",
     "parameters": {"type": "object", "properties": {"path": {"type": "string"}},
                    "required": ["path"], "additionalProperties": False}},
    {"type": "function", "name": "write_file",
     "description": "Replace a file in the repository with new content.",
     "parameters": {"type": "object",
                    "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
                    "required": ["path", "content"], "additionalProperties": False}},
    {"type": "function", "name": "run_tests",
     "description": "Run the test suite and return the last 200 lines of output.",
     "parameters": {"type": "object", "properties": {}, "additionalProperties": False}},
]

def safe_path(p: str) -> Path:
    full = (REPO / p).resolve()
    if not full.is_relative_to(REPO):
        raise ValueError("path escapes the repository")
    return full

def call_tool(name: str, args: dict) -> str:
    try:
        if name == "read_file":
            return safe_path(args["path"]).read_text(encoding="utf-8")[:200_000]
        if name == "write_file":
            safe_path(args["path"]).write_text(args["content"], encoding="utf-8")
            return "ok"
        if name == "run_tests":
            r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
            return "\n".join((r.stdout + r.stderr).splitlines()[-200:])
        return f"unknown tool {name}"
    except Exception as e:  # return errors to the model instead of crashing the loop
        return f"error: {e}"

エージェントは使い捨てのチェックアウトやコンテナに対して実行し、作業中のツリーに対しては決して実行しないでください。

上限付きのエージェントループ

このループは会話を送信し、すべての function_call アイテムを実行して、同じ call_id を持つ function_call_output を追加し、モデルがツール呼び出しなしで回答するまで繰り返します。ターン上限と金額の予算に達したら停止します。

PRICES = {"gpt-6.2-sol": (1.60, 8.00, 0.08, 2.00), "gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00)}

def cost(model, u) -> float:
    p_in, p_out, p_read, p_write = PRICES[model]
    d = getattr(u, "input_tokens_details", None)
    read = getattr(d, "cached_tokens", 0) or 0
    write = getattr(d, "cache_write_tokens", 0) or 0
    return ((u.input_tokens - read - write) * p_in + read * p_read
            + write * p_write + u.output_tokens * p_out) / 1e6

DEVELOPER = ("You are a coding agent working in a Python repository. "
             "Read files before editing. Run the tests after every change. "
             "When the tests pass, reply with a short summary and no tool call.")

def run_agent(task: str, model="gpt-6.2-sol", max_turns=30, budget_usd=3.00):
    items = [{"role": "developer", "content": DEVELOPER},
             {"role": "user", "content": task}]
    spent = 0.0
    for turn in range(max_turns):
        resp = client.responses.create(
            model=model, input=items, tools=TOOLS,
            reasoning={"effort": "medium"}, max_output_tokens=16000,
            store=False, include=["reasoning.encrypted_content"],
        )
        spent += cost(model, resp.usage)
        items += [o.model_dump(exclude_none=True) for o in resp.output]
        calls = [o for o in resp.output if o.type == "function_call"]
        if not calls:
            return resp.output_text, spent, turn + 1
        for c in calls:
            items.append({"type": "function_call_output", "call_id": c.call_id,
                          "output": call_tool(c.name, json.loads(c.arguments))})
        if spent >= budget_usd:
            break
    raise RuntimeError(f"stopped after {turn + 1} turns, ${spent:.3f} spent")

ループをこのように組んでいる理由:

  • 出力アイテムは推論アイテムも含めて順番どおりに戻す。 Zero Data Retentionの場合のように store がfalseのリクエストについて、OpenAIのGPT-6.2ガイドは「暗号化された推論アイテムを含め、前回の出力アイテムを順番どおりに戻してください」と述べています。include=["reasoning.encrypted_content"] はそれを要求するための指定です。代わりに、保存されたレスポンスと previous_response_id を使う方法もあり、こちらもPoYoのドキュメントに記載されています。
  • 履歴は追記のみ。 OpenAIは、会話の途中で編集するとResponses APIが推論アイテムを破棄することがあり、それが「回答の品質を下げ、トークン使用量を増やす可能性がある」と警告しています。また、編集するとキャッシュされたプレフィックスも崩れます。
  • 予算は毎ターン確認する。 請求と同じ価格表を使います。

この記事のために、このループそのものをPoYo上でエンドツーエンドで実行したわけではありません。まず小さなタスクで実行し、ツール呼び出しと usage が想定どおりになっているか確認してください。

進捗をユーザーにストリーミングする

エージェントのターンが長いと、フィードバックがなければ遅く感じられます。各ターンをストリーミングしてテキストの差分を表示し、最終出力は response.completed から取得します。以下はPoYoがドキュメント化しているイベントタイプです。

def stream_turn(model, items):
    final = None
    with client.responses.create(model=model, input=items, tools=TOOLS,
                                 reasoning={"effort": "medium"}, max_output_tokens=16000,
                                 store=False, include=["reasoning.encrypted_content"],
                                 stream=True) as stream:
        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
            elif event.type == "response.completed":
                final = event.response
            elif event.type == "response.failed":
                raise RuntimeError(event.response)
    return final  # same object as the non-streaming call: .output, .usage

ループ内の responses.create を stream_turn に置き換えてください。ツール呼び出しはこれまでどおり final.output から読み取ります。

長いコンテキスト:入力922K、出力128K

GPT-6.2は1リクエストあたり最大922,000の入力トークンを受け付けます。エージェントはファイルを1つずつ読む代わりに、リポジトリの大部分を最初に読み込めます。この選択を左右する制約は3つです。

  • 毎ターン履歴が再送される。 200Kトークンのスナップショットを20ターン使うと、入力は少なくとも4Mトークンになります。Solの$1.60では、キャッシュなしで$6.40です。スナップショットのキャッシュ書き込み1回($0.40)と$0.08でのキャッシュ読み取り19回($0.30)なら、約$0.70になります。
  • OpenAIの長コンテキスト料金は入力272Kトークン超から。 OpenAIの料金ページでは、このラインを超えるとリクエスト全体について入力料金とキャッシュ料金が2倍になり、出力は1.5×で課金されます。タスク上どうしても必要でない限りエージェントのリクエストは272K未満に抑え、適用されるPoYoの料金はモデルページで確認してください。
  • 推論は出力の予算を共有する。 max_output_tokens は表示されるテキストと推論の合計の上限です。リポジトリ全体の書き換えではなく、write_file の呼び出しごとに1ファイルを求めてください。

ツールの出力は追加する前に削りましょう。テスト実行の結果は20,000行ではなく最後の200行を返します。そうすればターンごとの増加量、ひいては請求額が、線形で小さく保たれます。

エージェントセッションのプロンプトキャッシュ

OpenAIのキャッシュガイドでは、GPT-6.2について次のルールが定められています。

ルール値
キャッシュ読み取りの価格入力の0.05×(PoYoで100万あたりSol $0.08、Astra $0.32)
キャッシュ書き込みの価格デフォルトの30分保持で入力の1.25×(PoYoで100万あたり$2 / $8)
キャッシュ可能なプレフィックスの最小サイズ表示される入力トークンで1,024
暗黙のブレークポイント対象となる最新のメッセージの末尾
使用量のフィールドusage.input_tokens_details.cached_tokens(読み取り)、cache_write_tokens(書き込み)

キャッシュヒットの可能性を高めるには:

  1. 固定の内容を先頭に置く。 developerメッセージ、ツール定義、リポジトリのスナップショット、タスクの順に並べます。
  2. トップレベルの instructions ではなく developer メッセージを使う。 GPT-6.2は instructions を input の後ろに追加するため、プレフィックスの外に置かれてしまいます。
  3. 以前のアイテムは決して編集しない。 ツールの出力は追記し、履歴は書き換えないでください。
  4. セッション内では設定を固定する。 OpenAIのガイドは、レスポンス間で設定を変える場合もプレフィックスは変えないよう述べています。

OpenAIは prompt_cache_options(明示的なブレークポイントと12時間の保持)もドキュメント化しています。PoYoのResponsesスキーマにはこのフィールドがなく、追加のフィールドを受け付けない(additionalProperties: false)と宣言されているため、指定せずに暗黙のキャッシュに任せてください。Solでの25ターンのセッションは、最良のケースでキャッシュなしの$3.82から約$0.74まで下がります。計算はGPT-6.2 APIの料金にあります。

Astraに実行を引き継ぐタイミング

すべての実行は gpt-6.2-sol で始めます。テストが失敗したままターン上限で止まった場合は、新しいアイテムリストで gpt-6.2-astra を使ってタスクをやり直します。OpenAIによればモデルの変更で推論アイテムが破棄されることがあるため、同じ会話の中でモデルを切り替えないでください。振り分けの計算とルーターはGPT-6.2 Sol API vs GPT-6.2 Astra APIにあります。別ベンダーで同じループを組んだ例としては、コーディングエージェント向けGemini 4 Carbon APIと比較してみてください。

よくある質問

GPT-6.2 APIは関数呼び出しに対応していますか?

はい、/v1/responses で対応しています。type: "function" でツールを定義し、output から function_call アイテムを読み取り、結果を同じ call_id を持つ function_call_output アイテムとして送り返します。

GPT-6.2 APIのツールをChat Completionsで使えますか?

いいえ。OpenAIによれば、GPT-6.2はChat Completionsに対応していますが、ツール呼び出しにはResponsesが必要です。

GPT-6.2 APIでエージェントのターンをストリーミングするには?

Responsesで stream: true を設定し、response.output_text.delta イベントを表示して、ツール呼び出しと usage は response.completed イベントから読み取ります。

長いエージェントセッションでGPT-6.2 APIの費用を抑えるには?

固定のプレフィックス(developerメッセージ、ツール、スナップショット)を先頭に置き、編集ではなく追記し、ツールの出力を削り、可能であればリクエストごとの入力を272Kトークン未満に抑えます。

コーディングエージェントにはどのGPT-6.2モデルを使うべきですか?

トークン単価がAstraの4分の1である gpt-6.2-sol から始め、失敗した実行は gpt-6.2-astra でやり直してください。

Share: