Премини към основното съдържание
Български— Изберете език
Меню

Анатомия на SDK: Агент, Изпълнител, Инструмент, Предпазна мярка

Урок 5 от 25 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Анатомия на SDK: Агент, Изпълнител, Инструмент, Предпазна мярка
  2. Агент: Конфигурация
  3. Изпълнител: Изпълнение
  4. Инструмент: Възможности
  5. Предпазна мярка: Сигурност
  6. Как тези части взаимодействат
  7. Ключови изводи

Анатомия на SDK: Агент, Изпълнител, Инструмент, Предпазна мярка

SDK за агенти се основава на четири основни концепции: Агент, Изпълнител (Runner), Инструмент и Предпазна мярка (Guardrail). Всяка от тях има една-единствена отговорност. Тяхното взаимодействие – кой решава, кой изпълнява, кой действа и кой контролира – е това, което прави SDK лесен за разбиране, след като го усвоите.

1

Агент — Мозъкът

Дефинира инструкциите, модела, инструментите и предпазните мерки. Това е конфигурацията на Вашия агент.

2

Изпълнител — Двигателят за изпълнение

Оркестрира цикъла на разсъждение: изпраща заявки, изпълнява инструменти и управлява предаването на контрола.

3

Инструмент — Възможности

Функции, които агентът може да извика: търсене в уеб, изпълнение на код, API повиквания и други.

4

Предпазна мярка — Сигурност

Валидира входовете и изходите на агента. Блокира опасни или извънтематични заявки.

Агент: Конфигурация

Класът Agent е чисто декларативен: той не изпълнява нищо, а описва. Всичко, което дефинира поведението на Вашия агент, се намира на едно място.

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
)

Основни параметри на Agent:

  • name: Идентификатор, четим от човек, за агента
  • instructions: Системният промпт, който дефинира поведението
  • model: Моделът, който да се използва (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Списъкът с налични инструменти
  • handoff_description: Описание, използвано при предаване на контрола между агенти
  • output_type: Pydantic тип за структуриране на изхода

Изпълнител: Изпълнение

Runner е двигателят, който изпълнява Вашия агент. Той управлява целия цикъл и предлага три режима в зависимост от контекста на извикване.

from agents import Runner

# Синхронен режим (разработка)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Асинхронен режим (продукция)
result = await Runner.run(agent, "What is the price of the widget?")

# Режим на потоково предаване (реално време)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Независимо от режима, получавате обект RunResult, който съдържа много повече от просто отговора за показване. Пълната история Ви позволява да възобновите разговор, а last_agent става съществено важен, щом множество агенти си предават контрола един на друг.

result = Runner.run_sync(agent, "What is the price of the widget?")

# Крайният отговор на агента
print(result.final_output)

# Пълната история на разговора
print(result.to_input_list())

# Последният активен агент (полезно при предаване на контрола)
print(result.last_agent.name)

Инструмент: Възможности

SDK поддържа три начина за деклариране на инструменти, от най-честия до най-архитектурния.

1. Функционални инструменти (най-чести)

Декорирана Python функция се превръща в инструмент; SDK извежда схемата автоматично от подписа и docstring-а.

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. Инструменти, хоствани от OpenAI

Тези инструменти се изпълняват от страна на OpenAI: Вие не пишете логиката за търсене или Python пясъчника.

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. Агенти като инструменти

Един агент може да използва друг като инструмент. Координаторът по-долу делегира проучването, без никога да отстъпва контрола над разговора, което го отличава от предаване на контрола (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"
    )],
)

Предпазна мярка: Сигурност

Предпазната мярка е контролиращ агент, поставен пред Вашия бизнес агент. Тук верификатор проверява дали заявката попада в сферата на продажбите, преди агентът за продажби да отговори.

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),
    ],
)

Ако предпазната мярка се активира (tripwire_triggered=True), изпълнението спира и се хвърля изключение InputGuardrailTripwireTriggered. Планирайте да прихванете това във Вашето приложение; в противен случай ще върнете грешка 500 на потребител, който просто е задал извънтематичен въпрос.

Как тези части взаимодействат

Пълният поток протича по следния начин:

  1. Вие извиквате Runner.run(agent, message)
  2. Изпълнителят проверява входните предпазни мерки
  3. Изпълнителят изпраща съобщението до модела на Агента
  4. Ако моделът поиска инструмент, Изпълнителят го изпълнява
  5. Изпълнителят връща резултата на модела (обратно към стъпка 3)
  6. Когато моделът генерира краен отговор, Изпълнителят проверява изходните предпазни мерки
  7. Връща се RunResult

Ключови изводи

  • Agent дефинира поведението (инструкции, модел, инструменти)
  • Runner оркестрира изпълнението на цикъла на агента
  • Декларирайте инструменти с @function_tool, вградени класове или .as_tool()
  • Предпазните мерки валидират входовете и изходите за сигурност
  • RunResult съдържа крайния отговор и пълната история