Оркестрация агентов: рутины и передача управления
Разбираем паттерны оркестрации из официального cookbook OpenAI: рутины (routines) как system prompt + инструменты, handoffs для передачи управления между агентами, и как это реализуется в Swarm.
Рутины и агенты
Рутина — это набор шагов: system prompt на естественном языке плюс инструменты для их выполнения. LLM-модели отлично справляются с условными переходами внутри рутины без жёсткой state machine.
from openai import OpenAI
import json
client = OpenAI()
system_message = (
"You are a customer support agent for ACME Inc."
"Follow the following routine with the user:"
"1. Ask probing questions to understand the user's problem.\n"
"2. Propose a fix (make one up).\n"
"3. ONLY if not satisfied, offer a refund.\n"
"4. If accepted, search for the ID and then execute refund."
)
def look_up_item(search_query):
"""Use to find item ID."""
return "item_132612938"
def execute_refund(item_id, reason="not provided"):
print(f"Refunding item {item_id}, reason: {reason}")
return "success"
Автоматическая схема функций
import inspect
def function_to_schema(func) -> dict:
type_map = {str: "string", int: "integer", float: "number",
bool: "boolean", list: "array", dict: "object"}
sig = inspect.signature(func)
parameters = {}
for param in sig.parameters.values():
param_type = type_map.get(param.annotation, "string")
parameters[param.name] = {"type": param_type}
required = [p.name for p in sig.parameters.values()
if p.default is inspect.Parameter.empty]
return {
"type": "function",
"function": {
"name": func.__name__,
"description": (func.__doc__ or "").strip(),
"parameters": {"type": "object", "properties": parameters,
"required": required},
},
}
Исполнение tool calls и handoffs
tools = [execute_refund, look_up_item]
tool_schemas = [function_to_schema(t) for t in tools]
tools_map = {t.__name__: t for t in tools}
def execute_tool_call(tool_call, tools_map):
name = tool_call.function.name
args = json.loads(tool_call.function.arguments)
return tools_map[name](**args)
Когда использовать handoffs
Handoff — это вызов функции, которая переключает активного агента. Каждый агент получает свой system prompt и набор инструментов. Triaging-агент маршрутизирует, специализированные агенты выполняют.
Реализуйте двухагентную систему: Triage Agent с инструментом transfer_to_refund, Refund Agent с инструментами look_up_item и execute_refund. Проверьте, что диалог корректно передаётся между агентами.
Скопируйте и адаптируйте под свой контекст. Текст в треугольных скобках — то, что нужно заменить.
tools = [look_up_item, execute_refund]
tool_schemas = [function_to_schema(t) for t in tools]
tools_map = {t.__name__: t for t in tools}
def run_full_turn(system_msg, messages):
while True:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "system", "content": system_msg}] + messages,
tools=tool_schemas,
)
msg = response.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg
for tc in msg.tool_calls:
result = execute_tool_call(tc, tools_map)
messages.append({"role": "tool",
"tool_call_id": tc.id, "content": result})Передавать управление агенту без смены system_message — агент продолжает работать со старыми инструкциями. Не сохранять tool_call_id в ответе — API вернёт ошибку валидации.
function_to_schema через inspect.signature избавляет от ручного описания схем. Библиотека Swarm от OpenAI реализует этот паттерн из коробки с поддержкой context variables.
Системы с несколькими специализированными ролями, где логика маршрутизации проста. Замена сложного if/else с явными переходами на LLM-управляемый flow.
Одиночные агенты без необходимости передачи управления. Задачи с жёсткой детерминированной логикой, где LLM-маршрутизация добавляет непредсказуемость.