Przejdź do głównej treści
Polski— Wybierz język
Menu

Anatomia SDK: Agent, Runner, Tool, Guardrail

Lekcja 5 z 25 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Anatomia SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Konfiguracja
  3. Runner: Wykonanie
  4. Tool: Możliwości
  5. Guardrail: Bezpieczeństwo
  6. Jak te elementy współdziałają
  7. Kluczowe wnioski

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.

1

Agent — Mózg

Definiuje instrukcje, model, narzędzia i zabezpieczenia. To konfiguracja Twojego agenta.

2

Runner — Silnik wykonawczy

Orkiestruje pętlę rozumowania: wysyła żądania, wykonuje narzędzia i obsługuje przekazywanie zadań.

3

Tool — Możliwości

Funkcje, które agent może wywołać: wyszukiwanie w sieci, wykonywanie kodu, wywołania API i inne.

4

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 agenta
  • instructions: Prompt systemowy definiujący zachowanie
  • model: Model do użycia (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Lista dostępnych narzędzi
  • handoff_description: Opis używany przy przekazywaniu zadań między agentami
  • output_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:

  1. Wywołujesz Runner.run(agent, message)
  2. Runner sprawdza guardraile wejściowe
  3. Runner wysyła wiadomość do modelu agenta
  4. Jeśli model zażąda narzędzia, Runner je wykonuje
  5. Runner zwraca wynik do modelu (powrót do kroku 3)
  6. Gdy model wygeneruje ostateczną odpowiedź, Runner sprawdza guardraile wyjściowe
  7. Zwracany jest obiekt RunResult

Kluczowe wnioski

  • Agent definiuje zachowanie (instrukcje, model, narzędzia)
  • Runner orkiestruje 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
  • RunResult zawiera ostateczną odpowiedź i pełną historię