Анатомия на SDK: Агент, Изпълнител, Инструмент, Предпазна мярка
На тази страница
Анатомия на SDK: Агент, Изпълнител, Инструмент, Предпазна мярка
SDK за агенти се основава на четири основни концепции: Агент, Изпълнител (Runner), Инструмент и Предпазна мярка (Guardrail). Всяка от тях има една-единствена отговорност. Тяхното взаимодействие – кой решава, кой изпълнява, кой действа и кой контролира – е това, което прави SDK лесен за разбиране, след като го усвоите.
Агент — Мозъкът
Дефинира инструкциите, модела, инструментите и предпазните мерки. Това е конфигурацията на Вашия агент.
Изпълнител — Двигателят за изпълнение
Оркестрира цикъла на разсъждение: изпраща заявки, изпълнява инструменти и управлява предаването на контрола.
Инструмент — Възможности
Функции, които агентът може да извика: търсене в уеб, изпълнение на код, API повиквания и други.
Предпазна мярка — Сигурност
Валидира входовете и изходите на агента. Блокира опасни или извънтематични заявки.
Агент: Конфигурация
Класът 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 на потребител, който просто е задал извънтематичен въпрос.
Как тези части взаимодействат
Пълният поток протича по следния начин:
- Вие извиквате
Runner.run(agent, message) - Изпълнителят проверява входните предпазни мерки
- Изпълнителят изпраща съобщението до модела на Агента
- Ако моделът поиска инструмент, Изпълнителят го изпълнява
- Изпълнителят връща резултата на модела (обратно към стъпка 3)
- Когато моделът генерира краен отговор, Изпълнителят проверява изходните предпазни мерки
- Връща се
RunResult
Ключови изводи
Agentдефинира поведението (инструкции, модел, инструменти)Runnerоркестрира изпълнението на цикъла на агента- Декларирайте инструменти с
@function_tool, вградени класове или.as_tool() - Предпазните мерки валидират входовете и изходите за сигурност
RunResultсъдържа крайния отговор и пълната история