Jak zacząć z Agents API OpenAI krok po kroku. Zarządzany Codex w becie

Jaki problem rozwiązuje Agents API

Agents API ma zdjąć z programistów obsługę pętli agenta. Do tej pory firma budująca agenta na Responses API sama zarządzała historią rozmowy, podsumowaniem kontekstu, ponawianiem kroków i stanem zadań. Według dokumentacji OpenAI nowy interfejs przejmuje sesje, orkiestrację, zarządzanie kontekstem i odzyskiwanie po błędach.

Podstawą jest zarządzany harness Codex, czyli warstwa sterująca pracą agenta znana z narzędzia Codex. Aplikacja dostarcza narzędzia i wybiera środowisko uruchomieniowe, a OpenAI prowadzi przebieg sesji. Dokumentacja wymienia cztery pojęcia: agenta (model, instrukcje, narzędzia), środowisko, trwałą sesję oraz zdarzenia wymieniane w trakcie pracy.

Zarządzany harness Codex obsługuje pełny cykl pracy agenta. Według dokumentacji agent może uruchamiać kod w sandboksie, edytować pliki, korzystać ze skilli i łączyć się z danymi zewnętrznymi przez narzędzia lub serwery MCP (Model Context Protocol, standard podłączania narzędzi do modeli).

• Wykonywanie kodu i edycja plików w sandboksie.
• Programowe wywoływanie narzędzi, wyszukiwanie w sieci i integracje MCP.
• Delegowanie podzadań do subagentów, maksymalnie 4 jednocześnie.
• Podsumowanie kontekstu i wznawianie sesji po przerwie.
• Śledzenie postępu przez streaming zdarzeń albo webhooki.

Przygotowanie przed pierwszym uruchomieniem

Do startu potrzebny jest projekt w OpenAI Platform, klucz API i aktualne SDK. Przykłady w dokumentacji korzystają z modelu gpt-6-astra, ale strona nie podaje pełnej listy obsługiwanych modeli.

Przed pierwszym testem warto zdecydować, gdzie agent będzie wykonywał kod. Środowisko openai_hosted oznacza sandbox OpenAI, a wartość none wyłącza sandbox, gdy agent korzysta tylko z zewnętrznych narzędzi. Dokumentacja opisuje też wariant self_hosted z własnym katalogiem roboczym.

• Konto z dostępem do API i rozliczeniami w OpenAI Platform.
• Klucz API projektu z uprawnieniami api.agents.read, api.agents.write i api.responses.write.
• SDK w Pythonie, JavaScripcie, Go, Javie lub Ruby.
• Decyzja o środowisku: openai_hosted, self_hosted albo none.

Agents API OpenAI krok po kroku

Poniższa procedura opiera się na oficjalnym quickstarcie Agents API. Nazwy parametrów i zdarzeń podajemy tak, jak zapisuje je OpenAI.

1. Utwórz w projekcie klucz API z uprawnieniami api.agents.read, api.agents.write i api.responses.write, najlepiej z datą wygaśnięcia.
2. Zapisz klucz w zmiennej środowiskowej OPENAI_API_KEY, a nie w kodzie aplikacji.
3. Zainstaluj SDK, np. pip install --upgrade openai dla Pythona albo npm install openai dla JavaScriptu.
4. Utwórz sesję z modelem (w przykładzie gpt-6-astra), instrukcjami, środowiskiem openai_hosted lub none, treścią zadania i parametrem stream ustawionym na true.
5. Obserwuj zdarzenia. Zdarzenie agent.session.turn.completed oznacza zakończoną turę, a turn.failed, turn.cancelled i session.failed sygnalizują problem.
6. Zapisz session_id i użyj go, aby wysłać kolejne polecenie w tej samej sesji albo skorygować kierunek pracy.
7. Po zakończeniu testu usuń sesję przez endpoint usuwania lub metodę SDK.

Przykład zastosowania w polskiej firmie

Software house z Wrocławia może zlecić agentowi przegląd zależności w repozytorium klienta. Agent w sandboksie OpenAI uruchamia testy, edytuje pliki i przygotowuje raport, a programista wysyła poprawki w tej samej sesji. Przy dłuższym zadaniu agent może rozdzielić pracę między subagentów, np. osobno dla frontendu i backendu.

Taki scenariusz ma sens tylko wtedy, gdy kod klienta może trafić na serwery w USA. Jeśli umowa wymaga przetwarzania w UE, beta Agents API nie spełni tego warunku w obecnej postaci.

Typowe błędy przy starcie

Większość problemów na początku wynika z konfiguracji, a nie z samego modelu. Na podstawie dokumentacji wskazujemy miejsca, które najczęściej trzeba sprawdzić. Przy pierwszym teście najlepiej ograniczyć zadanie do jednego repozytorium i jednego celu, aby łatwiej ocenić przebieg sesji i zużycie tokenów.

• Klucz bez uprawnień api.agents.write lub api.responses.write, przez co sesja się nie tworzy.
• Wywołania HTTP bez nagłówka OpenAI-Beta: agents=v1, gdy nie korzysta się z oficjalnego SDK.
• Ignorowanie zdarzeń turn.failed i session.failed zamiast obsługi błędów w aplikacji.
• Brak zapisu session_id, co uniemożliwia kontynuację pracy.
• Pozostawianie nieużywanych sesji, choć dokumentacja przewiduje ich usuwanie.

Koszt i ograniczenia bety

Dokumentacja nie wymienia osobnej opłaty za samo Agents API. Użycie modelu jest rozliczane według stawek wybranego modelu, narzędzia OpenAI według ich standardowych cen, a sandboksy hostowane przez OpenAI według standardowych stawek za kontenery. Końcowy koszt zależy więc od modelu, długości zadań i liczby subagentów.

Najpoważniejsze ograniczenie dotyczy danych. Beta obsługuje rezydencję danych wyłącznie w USA i nie wspiera Zero Data Retention, czyli trybu bez przechowywania danych po stronie OpenAI. Dokumentacja nie podaje też, jak długo przechowywane są sesje ani czy interfejs zmieni się przed wersją stabilną.

Bezpieczeństwo, firmy w Polsce i podsumowanie

Agent z dostępem do sandboksu, MCP i wyszukiwania w sieci może wykonywać realne działania, dlatego potrzebuje osobnego klucza z minimalnymi uprawnieniami. W ocenie redakcji dailyAI betę najlepiej testować na danych syntetycznych lub publicznych repozytoriach.

Źródła nie podają informacji o dostępności przetwarzania w UE dla Agents API. Dla firm z danymi osobowymi, objętymi RODO, to dziś warunek wykluczający produkcyjne wdrożenie. Zespoły, które potrzebują przetwarzania w Europie, mogą na razie zostać przy własnej pętli agenta na Responses API i wrócić do tematu po wyjściu z bety.

Status bety oznacza jednak, że interfejs może się jeszcze zmienić, a dane trafiają wyłącznie do USA. W ocenie redakcji dailyAI to dobry moment na prototypy i testy kosztów, ale za wcześnie na produkcyjne wdrożenia z danymi osobowymi lub poufnym kodem klientów.