how-tos

GPT-6.2 API для агентов разработки: function tools, стриминг, длинный контекст и кэширование

Poyo.ai Team
9 min read
Share:

GPT-6.2 API в цикле агента разработки

GPT-6.2 API — текущий выбор OpenAI для агентной работы: changelog API рекомендует gpt-6.2-sol «для повседневной разработки и агентных сценариев», а gpt-6.2-astra — для «требовательных задач на рассуждение и программирование». Это руководство подключает любую из моделей к агенту разработки через эндпоинт Responses в PoYo: function tools, ограниченный цикл, стриминг прогресса, большой контекст репозитория и кэширование, которое удерживает стоимость долгих сессий в разумных пределах. Начните на странице модели GPT-6.2 Sol, а GPT-6.2 Astra оставьте для эскалации.

Если вы ещё не отправили первый запрос, начните с руководства по GPT-6.2 API.

Что API даёт агенту разработки

ПараметрGPT-6.2 в PoYo
ID моделейgpt-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
Цена за 1M (Sol)$1.60 вход / $8 выход / $0.08 чтение из кэша / $2 запись в кэш
Цена за 1M (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 вызов функций и набор встроенных (hosted) инструментов. В документации PoYo в качестве примера встроенного инструмента показан только web_search_preview, поэтому этот агент использует ваши собственные function tools, которые вы полностью контролируете.

Определите function tools

Держите набор инструментов небольшим и безопасным. Модель может запрашивать только те действия, которые вы реализовали:

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}"

Запускайте агента на одноразовом checkout или в контейнере, но никогда не в своей рабочей копии.

Ограниченный цикл агента

Цикл отправляет диалог, выполняет каждый элемент function_call, добавляет function_call_output с тем же call_id и повторяет, пока модель не ответит без вызова инструмента. Он останавливается по лимиту ходов и по бюджету в долларах.

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")

Почему цикл устроен именно так:

  • Элементы вывода возвращаются по порядку, включая элементы рассуждений. Для запросов, где store равен false, как при Zero Data Retention, руководство 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

Подставьте stream_turn в цикл вместо responses.create. Вызовы инструментов читаются из final.output точно так же, как раньше.

Длинный контекст: 922K на входе, 128K на выходе

GPT-6.2 принимает до 922,000 входных токенов на запрос. Агент может сразу загрузить большую часть репозитория, а не читать файлы по одному. На этот выбор влияют три ограничения:

  • Каждый ход заново отправляет историю. Снимок на 200K токенов за 20 ходов — это минимум 4M входных токенов. По цене Sol $1.60 это $6.40 без кэша. С одной записью снимка в кэш ($0.40) и 19 чтениями из кэша по $0.08 ($0.30) — около $0.70.
  • Тариф OpenAI для длинного контекста начинается выше 272K входных токенов. За этой границей страница цен OpenAI удваивает ставки за вход и кэш и берёт 1.5× за выход на весь запрос. Держите запросы агента ниже 272K, если задаче не нужно больше, и сверяйтесь со страницей модели, чтобы узнать применимый тариф PoYo.
  • Рассуждения делят бюджет вывода. max_output_tokens ограничивает видимый текст вместе с рассуждениями. Просите один файл на вызов write_file, а не переписывание всего репозитория.

Обрезайте вывод инструментов перед добавлением в историю: возвращайте последние 200 строк прогона тестов, а не 20,000. Тогда прирост за ход — и счёт — остаются линейными и небольшими.

Кэширование промптов в агентных сессиях

Руководство OpenAI по кэшированию задаёт для GPT-6.2 следующие правила:

ПравилоЗначение
Цена чтения из кэша0.05× от входа ($0.08 за 1M на Sol, $0.32 на Astra, в PoYo)
Цена записи в кэш1.25× от входа при стандартном хранении 30 минут ($2 / $8 за 1M в PoYo)
Минимальный кэшируемый префикс1,024 видимых входных токена
Неявная точка разрываКонец последнего подходящего сообщения
Поля usageusage.input_tokens_details.cached_tokens (чтения), cache_write_tokens (записи)

Чтобы попадания в кэш были вероятнее:

  1. Ставьте стабильное содержимое первым. Сообщение developer, затем определения инструментов, затем снимок репозитория, затем задача.
  2. Используйте сообщение developer, а не instructions верхнего уровня. GPT-6.2 добавляет instructions после input, так что они окажутся вне префикса.
  3. Никогда не правьте предыдущие элементы. Добавляйте вывод инструментов; не переписывайте историю.
  4. Не меняйте настройки внутри сессии. Руководство OpenAI советует сохранять префикс неизменным, когда вы меняете настройки между ответами.

OpenAI также документирует prompt_cache_options (явные точки разрыва и хранение 12 часов). Схема Responses в PoYo это поле не перечисляет и закрыта для дополнительных полей (additionalProperties: false), поэтому не передавайте его и полагайтесь на неявное кэширование. Сессия на 25 ходов на Sol в лучшем случае дешевеет с $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", читайте элементы function_call из output и отправляйте результаты обратно как элементы function_call_output с тем же call_id.

Можно ли использовать инструменты GPT-6.2 API с Chat Completions?

Нет. OpenAI указывает, что GPT-6.2 поддерживает Chat Completions, но для вызова инструментов нужен Responses.

Как стримить ход агента в GPT-6.2 API?

Задайте stream: true в Responses, выводите события response.output_text.delta и читайте вызовы инструментов и usage из события response.completed.

Как снизить затраты на GPT-6.2 API в долгих агентных сессиях?

Держите стабильный префикс (сообщение developer, инструменты, снимок) в начале, дополняйте историю вместо правок, обрезайте вывод инструментов и по возможности укладывайтесь в 272K входных токенов на запрос.

Какая модель GPT-6.2 должна запускать моего агента разработки?

Начните с gpt-6.2-sol, который стоит за токен четверть цены Astra, и перезапускайте неудачные запуски на gpt-6.2-astra.

Share: