Anatomia SDK: Agent, Runner, Tool, Guardrail
Na tej stronie
Anatomia SDK: Agent, Runner, Tool, Guardrail
SDK Agents opiera się na czterech kluczowych koncepcjach: Agent, Runner, Tool i Guardrail. Każda z nich ma jedno, ściśle określone zadanie. To właśnie ich współdziałanie – kto decyduje, kto wykonuje, kto działa, kto kontroluje – sprawia, że SDK staje się czytelne, gdy tylko je zrozumiesz.
Agent — Mózg
Definiuje instrukcje, model, narzędzia i zabezpieczenia. To konfiguracja Twojego agenta.
Runner — Silnik wykonawczy
Orkiestruje pętlę rozumowania: wysyła żądania, wykonuje narzędzia i obsługuje przekazywanie zadań.
Tool — Możliwości
Funkcje, które agent może wywołać: wyszukiwanie w sieci, wykonywanie kodu, wywołania API i inne.
Guardrail — Bezpieczeństwo
Weryfikuje dane wejściowe i wyjściowe agenta. Blokuje niebezpieczne lub niezwiązane z tematem żądania.
Agent: Konfiguracja
Klasa Agent jest czysto deklaratywna: niczego nie uruchamia, jedynie opisuje. Wszystko, co definiuje zachowanie Twojego agenta, znajduje się w jednym miejscu.
from agents import Agent, function_tool, WebSearchTool
@function_tool
def get_price(product: str) -> str:
"""Retrieves the price of a product."""
prices = {"widget": "€29.99", "gadget": "€49.99"}
return prices.get(product, "Unknown product")
agent = Agent(
name="Sales Agent",
instructions="""You are a sales agent for an online store.
Help customers find products and learn their prices.
Always respond in French with a professional tone.""",
model="gpt-5.6-terra",
tools=[get_price, WebSearchTool()],
handoff_description="Agent specialized in selling products",
output_type=None, # or a Pydantic type to enforce an output format
)
Kluczowe parametry Agent:
name: Czytelny dla człowieka identyfikator agentainstructions: Prompt systemowy definiujący zachowaniemodel: Model do użycia (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Lista dostępnych narzędzihandoff_description: Opis używany przy przekazywaniu zadań między agentamioutput_type: Typ Pydantic strukturyzujący dane wyjściowe
Runner: Wykonanie
Runner to silnik uruchamiający Twojego agenta. Zarządza całą pętlą i występuje w trzech trybach, w zależności od kontekstu wywołania.
from agents import Runner
# Tryb synchroniczny (rozwój)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Tryb asynchroniczny (produkcja)
result = await Runner.run(agent, "What is the price of the widget?")
# Tryb strumieniowy (czas rzeczywisty)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Niezależnie od trybu otrzymujesz obiekt RunResult, który zawiera znacznie więcej niż sam wyświetlany ответ. Pełna historia pozwala wznowić rozmowę, a last_agent staje się kluczowy, gdy wiele agentów przekazuje sobie zadania.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Ostateczna odpowiedź agenta
print(result.final_output)
# Pełna historia rozmowy
print(result.to_input_list())
# Ostatni aktywny agent (przydatne przy przekazywaniu zadań)
print(result.last_agent.name)
Tool: Możliwości
SDK obsługuje trzy sposoby deklarowania narzędzi, od najczęstszych po najbardziej architektoniczne.
1. Narzędzia funkcyjne (najczęstsze)
Dekorowana funkcja Pythona staje się narzędziem; SDK wnioskuję schemat na podstawie sygnatury i docstringa.
from agents import function_tool
@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
"""Sends an email to a recipient."""
# Your sending logic here
return f"Email sent to {recipient}"
2. Narzędzia hostowane przez OpenAI
Te narzędzia działają po stronie OpenAI: nie piszesz logiki wyszukiwania ani piaskownicy Pythona.
from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool
tools = [
WebSearchTool(), # Web search
FileSearchTool(vector_store_ids=["vs_123"]), # File search
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}), # Code execution
]
3. Agenci jako narzędzia
Jeden agent może używać innego jako narzędzia. Poniższy koordynator deleguje badania, nigdy nie tracąc kontroli nad rozmową, co odróżnia to od przekazania zadania (handoff).
search_agent = Agent(
name="Researcher",
instructions="You look up precise information.",
tools=[WebSearchTool()],
)
primary_agent = Agent(
name="Coordinator",
instructions="You coordinate research.",
tools=[search_agent.as_tool(
tool_name="search",
tool_description="Performs in-depth research"
)],
)
Guardrail: Bezpieczeństwo
Guardrail to agent kontrolny umieszczony przed Twoim agentem biznesowym. Tutaj weryfikator sprawdza, czy żądanie dotyczy sprzedaży, zanim agent sprzedażowy odpowie.
from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
guardrail_agent = Agent(
name="Verifier",
instructions="Determine whether the request concerns sales. Respond true or false.",
output_type=bool,
)
async def verify_topic(ctx, agent, input_data):
result = await Runner.run(guardrail_agent, input_data, context=ctx)
return GuardrailFunctionOutput(
output_info=result.final_output,
tripwire_triggered=not result.final_output,
)
protected_agent = Agent(
name="Protected Sales Agent",
instructions="You are a sales agent.",
input_guardrails=[
InputGuardrail(guardrail_function=verify_topic),
],
)
Jeśli guardrail zostanie uruchomiony (tripwire_triggered=True), wykonanie zostaje przerwane, a wyjątek InputGuardrailTripwireTriggered jest zgłaszany. Zaplanuj jego obsługę w swojej aplikacji; w przeciwnym razie zwrócisz błąd 500 użytkownikowi, który po prostu zadał pytanie niezwiązane z tematem.
Jak te elementy współdziałają
Pełny przepływ wygląda następująco:
- Wywołujesz
Runner.run(agent, message) - Runner sprawdza guardraile wejściowe
- Runner wysyła wiadomość do modelu agenta
- Jeśli model zażąda narzędzia, Runner je wykonuje
- Runner zwraca wynik do modelu (powrót do kroku 3)
- Gdy model wygeneruje ostateczną odpowiedź, Runner sprawdza guardraile wyjściowe
- Zwracany jest obiekt
RunResult
Kluczowe wnioski
Agentdefiniuje zachowanie (instrukcje, model, narzędzia)Runnerorkiestruje wykonanie pętli agenta- Deklaruj narzędzia za pomocą
@function_tool, wbudowanych klas lub.as_tool() - Guardraile walidują dane wejściowe i wyjściowe pod kątem bezpieczeństwa
RunResultzawiera ostateczną odpowiedź i pełną historię