Първи OpenAI агент: ключът за API не трябва да влиза в sandbox

За да създадете агент, който пише и изпълнява скрипт в управлявана среда, използвайте началния пример за Agents API: приложението подава задачата с ключа за API, а OpenAI управлява сесията и sandbox средата. Ключът остава в приложението и не се предава на кода, който агентът създава.

Изборът на инструмент зависи от мястото на изпълнение. Agents SDK управлява цикъла на агента във вашето приложение; Agents API предоставя управляван от OpenAI цикъл. Примерът по-долу използва Agents API, защото задачата включва създаване и стартиране на файл в предоставен sandbox.

Подгответе ключа и правата

Създайте ключ за приложението в проекта си в OpenAI Platform. За сесиите му дайте правата api.agents.read и api.agents.write, а за извикването на модела — api.responses.write. Задайте го като OPENAI_API_KEY в средата на процеса, от който стартирате клиента. Това е процесът на вашето приложение, а не средата, в която агентът ще изпълнява команди.

За JavaScript инсталирайте клиентската библиотека с npm install openai. Разработчиците на Python могат да използват pip install --upgrade openai и клиента OpenAI(); съответният метод е client.beta.agents.sessions.create(). И в двата езика клиентската библиотека изпраща заявката към Agents API. Самото ѝ инсталиране на вашата машина не премества агентния цикъл там.

Създайте сесия и изпълнете скрипт

Следният минимален пример за JavaScript възлага на агента да създаде tree.py, да го стартира и да върне действителния изход. Стартирайте командата в терминал, в който OPENAI_API_KEY вече е зададен. Стойността на ключа не присъства нито в командата, нито в задачата към агента.

node --input-type=module -e 'import OpenAI from "openai"; const events = await new OpenAI().beta.agents.sessions.create({agent:{model:"gpt-6-astra",instructions:"Write a small script, run it, and report the actual output."},environment:{type:"openai_hosted"},input:"Create tree.py to print an indented tree of the current directory. Run it and show the output.",stream:true}); events.withResultCollection(); try { for await (const event of events) console.log(JSON.stringify(event)); const result = await events.finalResult(); console.log(result.output_text); console.log(result.session_id); } finally { events.controller.abort(); }'

В заявката agent задава модела и постоянните инструкции за тази сесия, а input съдържа конкретната задача. environment.type: openai_hosted избира управлявания sandbox. stream: true връща събития по време на работата; withResultCollection() позволява след потока да се вземе крайният резултат чрез finalResult(). Командата извежда и session_id, който е нужен, ако искате да продължите същата сесия.

Път на изпълнението: приложение с OPENAI_API_KEY → Agents API и сесия → управляван sandbox, в който се създава и стартира tree.py → събития и резултат обратно към приложението. Тази граница обяснява защо агентът може да работи с файлове, без да получава ключа, с който приложението е започнало сесията.

Разчетете потока преди повторен опит

При успешно изпълнение агентът трябва да създаде tree.py, да го стартира и да отчете резултат, в който се вижда и създаденият файл. Останалото съдържание на директорията може да е различно. Проверявайте отчетения изход от командата, а не само текста на финалния отговор: агентът може да опише намерение за действие, което не е завършило успешно.

Събитието agent.session.turn.completed означава, че ходът е приключил, но само по себе си не доказва успеха на всяка команда. Събития с край turn.failed, turn.cancelled или session.failed сочат неуспех или прекъсване. Ако потокът се затвори преждевременно, прегледайте състоянието и запазените елементи на сесията, преди да изпратите същата задача отново: първият опит може вече да е оставил файл или друг резултат.

Ако ще възлагате следваща задача върху същите файлове, запазете session_id и продължете съществуващата сесия. Когато работата приключи, първо изтеглете нужните файлове, после изтрийте сесията. Така не губите резултат, който е останал само в управляваната среда.

Дръжте тайните от правилната страна на границата

Указанията за сигурност на sandbox посочват същественото ограничение: генерираният от агента код може да чете файловете и идентификационните данни, достъпни в неговата среда. Затова не записвайте ключа на приложението в обработван файл, инструкция към агента, контейнерен образ или лог. Поставянето на секрет в обикновена променлива на средата в sandbox също го прави достъпен за изпълнявания код.

При собствен sandbox има отделен ключ за свързване на изпълнителя, подаван като CODEX_API_KEY. Той е ограничен до тази връзка и не заменя OPENAI_API_KEY, с който приложението прави API заявки. За достъп от управляван sandbox до външна услуга използвайте хранилището за тайни и разрешени мрежови дестинации: кодът работи със заместител, а мрежовият прокси подава истинската тайна към одобрената дестинация.

Кога да използвате Agents SDK

Изберете Agents SDK, когато вашето приложение трябва да управлява инструментите, състоянието, съхранението и решенията за одобрение. Тогава цикълът на агента работи във вашия процес, а нужната изолирана среда се конфигурира отделно. Изберете Agents API, когато искате OpenAI да управлява цикъла и сесията, както при задачата с tree.py.

Не бъркайте пакета openai от примера с Agents SDK. Той е клиентската библиотека, чрез която приложението извиква Agents API. Ако създаването на сесия бъде отказано, проверете правата на ключа на приложението. Ако сесията тръгне, но файлът или резултатът липсва, разгледайте събитията и изпълнението в sandbox. Това разграничение насочва проверката към мястото, където действително е възникнал проблемът.

Прочетете също:

• OpenAI API или Claude API: евтиният токен не гарантира евтина задача
• FTC разследва OpenAI и Anthropic — безопасността влиза в досието
• Лимитът за OpenAI API спира разхода — и може да спре продукцията