Rozpakowanie OpenAI Agents SDK: przewodnik

OpenAI wprowadza kilka nowych ofert: Responses API, wbudowane narzędzia do wyszukiwania w sieci i plikach, narzędzie do obsługi komputera oraz otwartoźródłowy Agents SDK. Podczas gdy Responses API pozwala deweloperom budować agentów na bazie tej technologii, Agents SDK może pomóc łączyć agentów z innymi narzędziami i procesami w sieci, realizując autonomicznie „przepływy pracy” wykonujące to, czego chce użytkownik lub firma.

Rok 2025 bywa określany jako „Rok Agentów”, a ruch OpenAI jest postrzegany jako kluczowy krok dla branży. Agents SDK pozwala deweloperom łatwo wykorzystać najnowsze osiągnięcia OpenAI (takie jak ulepszone rozumowanie, interakcje multimodalne i nowe techniki bezpieczeństwa) w rzeczywistych, wieloetapowych scenariuszach. Dla twórców LLM i budowniczych agentów AI Agents SDK dostarcza zestaw „bloków konstrukcyjnych” do tworzenia i zarządzania własnymi autonomicznymi systemami AI.

Znaczenie Agents SDK polega na zdolności do rozwiązywania wyzwań związanych z wdrażaniem agentów AI w środowiskach produkcyjnych. Tradycyjnie przekładanie potężnych możliwości LLM na wieloetapowe przepływy pracy było pracochłonne, wymagało wielu własnych reguł, sekwencyjnego projektowania promptów oraz metody prób i błędów bez odpowiednich narzędzi obserwowalności. Dzięki Agents SDK i powiązanym nowym narzędziom API, takim jak Responses API, OpenAI dąży do znaczącego uproszczenia tego procesu, umożliwiając tworzenie bardziej złożonych i niezawodnych agentów mniejszym nakładem pracy.

Czym jest Agents SDK

OpenAI w dużym stylu wraca do open source, udostępniając Agents SDK — zestaw narzędzi zaprojektowany, aby pomóc deweloperom zarządzać, koordynować i optymalizować przepływy pracy agentów — a nawet budować agentów zasilanych innymi, niebędącymi produktami OpenAI modelami, takimi jak konkurencyjne Anthropic i Google, czy otwartoźródłowe modele DeepSeek, Qwen, Mistral oraz rodzina Llama od Meta.

Dlaczego warto używać Agents SDK

SDK kieruje się dwoma nadrzędnymi zasadami projektowymi:

1. Wystarczająco dużo funkcji, by było warte użycia, ale na tyle mało prymitywów, by szybko się go nauczyć.
2. Działa świetnie od razu po instalacji, ale pozwala dokładnie dostosować zachowanie.

Oto główne funkcje SDK:

• Agent loop: Wbudowana pętla agenta, która obsługuje wywoływanie narzędzi, przekazywanie wyników do LLM i pętlę aż do zakończenia działania LLM.
• Python-first: Wykorzystuj wbudowane możliwości języka do orkiestracji i łączenia agentów zamiast uczyć się nowych abstrakcji.
• Handoffs: Potężna funkcja do koordynacji i delegowania zadań między wieloma agentami.
• Guardrails: Uruchamiaj walidacje i kontrole wejść równolegle do działania agentów, z możliwością wczesnego przerwania w razie niepowodzenia.
• Function tools: Zamień dowolną funkcję Pythona w narzędzie z automatycznym generowaniem schematu i walidacją opartą na Pydantic.
• Tracing: Wbudowane śledzenie pozwalające wizualizować, debugować i monitorować przepływy pracy oraz korzystać z zestawu narzędzi OpenAI do ewaluacji, dostrajania i destylacji.

How to use Openai Agents SDK

1. Skonfiguruj środowisko Pythona

python -m venv env
source env/bin/activate

2. Zainstaluj Agents SDK

pip install openai-agents

3. ustaw zmienną środowiskową OPENAI_API_KEY

Swobodnie ustaw OPENAI_API_KEY przez API CometAPI

• Zaloguj się do cometapi.com. Jeśli nie jesteś jeszcze naszym użytkownikiem, najpierw się zarejestruj
• Uzyskaj klucz API uprawniający dostęp do interfejsu. Kliknij „Add Token” w sekcji tokenu API w centrum osobistym, pobierz klucz tokenu: sk-xxxxx i zatwierdź.
• Pobierz adres URL tej usługi: https://api.cometapi.com/
• Wybierz endpoint OPENAI_API_KEY, aby wysłać żądanie API i ustaw treść żądania. Metodę i treść żądania znajdziesz w dokumentacji API na naszej stronie. Nasza strona oferuje także testy w Apifox dla Twojej wygody.

4. Skonfiguruj agenta

Zdefiniuj, z jakich narzędzi może korzystać Twoje AI. Załóżmy, że chcemy włączyć wyszukiwanie w sieci oraz pobieranie plików:

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=)

Teraz Twój agent wie, jak przeszukiwać sieć i pobierać dokumenty.

5. uruchom

W przeciwieństwie do tradycyjnych chatbotów to AI decyduje, którego narzędzia użyć na podstawie danych od użytkownika:

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

Bez ręcznej interwencji — po prostu autonomiczne wykonanie.

Pętla agenta

Po wywołaniu Runner.run() SDK uruchamia pętlę, aż uzyska wynik końcowy:

1. LLM jest wywoływany z użyciem modelu i ustawień agenta oraz historii wiadomości.
2. LLM zwraca odpowiedź, która może zawierać wywołania narzędzi.
3. Jeśli odpowiedź zawiera wynik końcowy, pętla kończy się i zwraca go.
4. Jeśli odpowiedź zawiera handoff, agent zostaje ustawiony na nowego agenta i pętla trwa od kroku 1.
5. Wywołania narzędzi są przetwarzane (jeśli występują) i dołączane są wiadomości z odpowiedziami narzędzi. Następnie pętla trwa od kroku 1.

Aby ograniczyć liczbę iteracji pętli, możesz użyć parametru max_turns.

​Wynik końcowy

Wynik końcowy to ostatnia rzecz, jaką agent generuje w pętli:

• Jeśli ustawisz na agencie output_type, wynikiem końcowym jest chwila, gdy LLM zwróci coś tego typu, korzystając z ustrukturyzowanych wyników.
• Jeśli nie ma output_type (tj. odpowiedzi w zwykłym tekście), to pierwsza odpowiedź LLM bez wywołań narzędzi ani handoffów jest uznawana za wynik końcowy.

Przykład Hello world

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,

# Functions calling themselves,
# Infinite loop's dance.

Struktura techniczna

„OpenAI Agents SDK ma być ramą koncepcyjną pokazującą, w jaki sposób różni agenci — tacy jak ‘Triage Agent’ czy ‘CRM Agent’ — mogą współpracować przy realizacji zadań poprzez interakcje z narzędziami i mechanizmy delegowania.”

Kluczowe komponenty i architektura Agents SDK

OpenAI Agents SDK opiera się na zwięzłym, lecz solidnym zestawie zasad. W jego rdzeniu znajduje się koncepcja Agenta, który reprezentuje instancję modelu językowego dopasowaną określonymi instrukcjami i wyposażoną w obsługę różnych narzędzi. Agenci zaczynają od przyjęcia żądania użytkownika — np. pytania lub definicji zadania — następnie rozbijają je na podzadania, które mogą wymagać użycia predefiniowanych narzędzi, a finalnie dostarczają kompletną odpowiedź. Te Narzędzia są funkcjonalnie opisane jako wywoływalne funkcje; dzięki Agents SDK każda funkcja Pythona może bez trudu pełnić rolę narzędzia, z automatyczną walidacją schematów wejść i wyjść zapewnianą przez Pydantic. Na przykład funkcje Pythona reprezentujące narzędzie zapytań do bazy danych lub narzędzie wyszukiwania w sieci można bezpośrednio zintegrować z zestawem narzędzi agenta.

Kolejnym kluczowym elementem Agents SDK jest Agent Loop, który definiuje iteracyjny proces rozwiązywania zadań. Zaczynając od wstępnej próby odpowiedzi na zapytanie, agent ocenia, czy ma wystarczające informacje, czy musi wykonać działania zewnętrzne. Gdy jest to potrzebne, wywołuje odpowiednie narzędzie, przetwarza wynik i ponownie ocenia zadanie. Cykl ten powtarza się, aż agent zasygnalizuje zakończenie zadania komunikatem „I’m done”. Agents SDK zarządza tym procesem autonomicznie, upraszczając tworzenie poprzez automatyzację powtarzalnych zadań, takich jak wywoływanie narzędzi, obsługa wyników i iteracyjne próby. Dzięki temu deweloperzy mogą skupić się na definiowaniu przepływów pracy i możliwości agentów bez martwienia się o mechanikę pod spodem. OpenAI opisuje to podejście jako Python-first, podkreślając użycie znanych konstrukcji Pythona — takich jak pętle, instrukcje warunkowe i wywołania funkcji — zamiast języków dziedzinowych (DSL). Z tą elastycznością deweloperzy mogą orkiestrwać współpracujących agentów, opierając się na natywnej składni Pythona.

Handoff i architektura multi-agentowa

Możliwości SDK wykraczają poza pojedynczych agentów. Dzięki funkcji znanej jako Handoff zadania mogą być przekazywane pomiędzy wieloma agentami, co umożliwia im bezproblemową współpracę. Na przykład „Triage Agent” może określić charakter przychodzącego zapytania, delegując je do innego wyspecjalizowanego agenta, lub wynik jednego agenta może posłużyć jako wejście dla innego. System ten wspiera przepływy pracy, w których wyspecjalizowani agenci realizują odrębne części szerszego zadania, umożliwiając złożone architektury multi-agentowe. OpenAI zaprojektowało zestaw narzędzi z myślą o skalowalnych zastosowaniach, takich jak automatyzacja wsparcia klienta, procesy badawcze, projekty wieloetapowe, tworzenie treści, operacje sprzedażowe czy nawet przeglądy kodu. Dodatkowo Guardrails zwiększają niezawodność poprzez narzucanie reguł walidacji dla wejść lub wyjść agenta. Przykładowo guardrails mogą wymuszać zgodność formatów parametrów lub kończyć pętlę wcześniej w razie wykrycia anomalii, ograniczając ryzyka takie jak nieefektywne wykonanie czy niepożądane zachowania w warunkach produkcyjnych.

Orkiestracja i monitorowanie

Poza samym wykonywaniem zadań Agents SDK zawiera rozbudowane funkcje orkiestracji, przejmując sterowanie wykonywaniem narzędzi, przepływami danych i zarządzaniem pętlą. Pomimo wysokiego poziomu automatyzacji OpenAI kładzie nacisk na przejrzystość, wyposażając deweloperów w narzędzia do monitorowania aktywności agentów w czasie rzeczywistym. Dzięki wbudowanej funkcji Tracing dostępnej w panelu OpenAI deweloperzy mogą wizualizować przepływy pracy krok po kroku, obserwując, kiedy wywoływane są narzędzia, jakie przyjmują wejścia i jakie zwracają wyjścia. Platforma wykorzystuje infrastrukturę monitorowania OpenAI, aby rozbić wykonanie logiki agenta na trasy (traces) i zakresy (spans), oferując szczegółowe wglądy w zachowanie agenta. Umożliwia to diagnozowanie wąskich gardeł, debugowanie problemów, optymalizację przepływów oraz śledzenie wydajności. Co więcej, architektura śledzenia wspiera zaawansowane ewaluacje, umożliwiając dostrajanie i poprawę działania agentów w czasie.

Zalety

OpenAI Agents SDK to nie tylko narzędzie dla indywidualnych deweloperów — przynosi też istotne korzyści firmom budującym produkty oparte na agentach AI. Zacznijmy od zalet:

Szybkie prototypowanie i produkcja: Agents SDK implementuje złożone zachowania agentów przy minimalnej ilości kodu i konfiguracji, skracając cykl od pomysłu do produktu. Na przykład wiodąca platforma kryptowalutowa Coinbase wykorzystuje SDK do szybkiego prototypowania i wdrażania wieloagentowych systemów wsparcia. Podobnie w obszarach takich jak asystenci wyszukiwania korporacyjnego firmy mogą zintegrować narzędzia wyszukiwania w sieci i plikach z SDK, aby szybko dostarczać wartość. Dzięki odciążeniu szczegółów orkiestracji deweloperzy mogą skupić się na funkcjach specyficznych dla produktu.

Obniżone koszty rozwoju: Zbudowanie systemu agentów od zera wymaga znaczących nakładów inżynieryjnych. Agents SDK redukuje koszty, dostarczając gotowe rozwiązania typowych potrzeb — zarządzanie pętlą, synchronizację wywołań API, obsługę błędów oraz formatowane wyjścia narzędzi dla LLM. Jako projekt open source pozwala też na dostosowanie do potrzeb firmy. To duża korzyść dla startupów, umożliwiając tworzenie potężnych produktów opartych na agentach przy ograniczonych zasobach.

Śledzalność i debugowanie: Zintegrowany pulpit śledzenia w SDK zmienia oblicze aplikacji biznesowych. Branżowe obawy, że AI to „czarna skrzynka”, ustępują miejsca możliwości logowania i audytowania każdego kroku agenta. Jeśli agent wsparcia klienta udzieli błędnej odpowiedzi, ślad pokaże, które wywołanie narzędzia lub krok zawiódł. Ekran logów/tras Platformy OpenAI poprawia audytowalność agentów — kluczową w branżach objętych regulacjami lub audytami wewnętrznymi. Umożliwia to firmom integrację AI z większą pewnością, wiedząc, że w razie potrzeby potrafią wyjaśnić wyniki.

Dostęp do najnowszych modeli i narzędzi OpenAI: Korzystanie z Agents SDK oznacza wykorzystanie najlepszych modeli OpenAI (np. GPT-4) i bieżących narzędzi (wyszukiwanie w sieci, wykonywanie kodu). To przewaga jakościowa nad budowaniem alternatyw opartych na słabszych modelach. W aplikacjach wymagających wysokiej dokładności lub aktualnych informacji (np. asystenci badawczy, agenci analizy finansowej) wydajność modeli OpenAI stanowi dużą zaletę. W miarę dodawania kolejnych narzędzi (zapowiadane są dalsze integracje) użytkownicy SDK mogą łatwo je adoptować.

CometAPI jest w pełni zgodny z protokołem interfejsu OpenAI, co zapewnia bezproblemową integrację. Możesz uniknąć zależności od modeli i usług (ryzyka lock-in), zmniejszyć obawy dotyczące prywatności i bezpieczeństwa danych oraz obniżyć koszty. Wykorzystanie potężnych modeli i narzędzi OpenAI może być kosztowne i czasem ograniczać wydajność. CometAPI oferuje niższe ceny.

Wnioski

OpenAI konsekwentnie rozwija możliwości AI dzięki innowacyjnym rozwiązaniom takim jak Responses API. Wprowadzając te narzędzia, firmy i deweloperzy zyskują szansę budowania mądrzejszych, bardziej elastycznych i wysoce niezawodnych rozwiązań AI. Te zmiany wskazują na przyszłość, w której sztuczna inteligencja będzie nadal wywierać istotny wpływ i odblokowywać nowe możliwości w różnych branżach.