Асинхронни и паралелни инструменти
На тази страница
Асинхронни и паралелни инструменти
В производствена среда Вашите инструменти извикват външни API, правят заявки към бази данни или изпълняват операции за вход/изход (I/O). Тези операции отнемат време, което се натрупва: агент, който верижно изпълнява пет едносекундни извиквания, ще отговори след пет секунди. Превръщането на инструментите в асинхронни и използването на вградения паралелизъм на SDK е това, което отличава демонстрационния проект от usable услуга.
Асинхронни инструменти
Декораторът @function_tool поддържа нативно async функции. Не се изисква конфигурация: просто декларирайте async def, използвайте асинхронен HTTP клиент и SDK ще се погрижи за останалото.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Търси информация за компания чрез API на Societe.com."""
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.societe.com/v1/search",
params={"q": name},
timeout=10,
)
if response.status_code == 200:
data = response.json()
return f"Company: {data['name']}, SIREN: {data['siren']}, Revenue: {data['revenue']}"
return f"No results for '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Проверява платежоспособността на компания по нейния SIREN номер."""
async with httpx.AsyncClient() as client:
response = await client.get(
f"https://api.credit-scoring.com/v1/{siren}",
timeout=10,
)
data = response.json()
return f"Solvency score: {data['score']}/100, risk: {data['risk_level']}"
Когато Runner изпълни асинхронен инструмент, той не блокира цикъла на събитията. В сървър на FastAPI това означава, че други заявки продължават да се обработват, докато Вашият агент чака отговор от API на Societe.com.
Автоматичен паралелизъм
Два независими асинхронни инструмента могат да се изпълняват едновременно. Моделът решава това, а Вашите инструкции могат изрично да го насърчат.
from agents import Agent, Runner
agent = Agent(
name="B2B Analyst",
instructions="""Вие анализирате компании за бизнес решения.
Когато Ви поискат да анализирате компания, извлечете нейната информация
И проверете нейната платежоспособност едновременно.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# Моделът ще стартира двата инструмента паралелно
result = await Runner.run(
agent,
"Analyze the company Acme Corp (SIREN 123456789)"
)
Тъй като SIREN е предоставен в заявката, проверката за платежоспособност не чака търсенето на компанията: SDK изпълнява двете извиквания едновременно. Общото време е равно на продължителността на най-бавния инструмент, а не на сбора от двете.
Контрол на паралелизма
Паралелизмът не винаги е желателен. Ако Вашите инструменти записват в един и същи запис или ако редът е важен за целостта на данните, принудете последователно изпълнение.
from agents import Agent
agent = Agent(
name="Cautious Agent",
instructions="Изпълнявайте инструментите един по един, за да осигурите цялост на данните.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Принуждава последователно изпълнение
)
Параметърът parallel_tool_calls=False принуждава модела да извиква само един инструмент в даден момент. Вие разменяте латентност за предвидимост.
Шаблон: Агрегиране на паралелни резултати
Най-честият практически случай включва събиране на данни от множество източници за един и същи обект. Тук времето и културната програма на даден град нямат нищо общо едно с друго, но отговорът се нуждае и от двете.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Получава текущото време за даден град."""
# Симулация - в продукция: извикване на weather API
weather_data = {
"Paris": {"temp": 22, "conditions": "sunny"},
"Lyon": {"temp": 19, "conditions": "cloudy"},
"Marseille": {"temp": 26, "conditions": "sunny"},
}
data = weather_data.get(city, {"temp": 0, "conditions": "unknown"})
return json.dumps({"city": city, **data}, ensure_ascii=False)
@function_tool
async def get_events(city: str) -> str:
"""Получава предстоящи събития в даден град."""
events = {
"Paris": ["Concert at Stade de France", "Exhibition at the Louvre"],
"Lyon": ["Festival of Lights", "Gastronomy Fair"],
"Marseille": ["Mediterranean Regatta"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Travel Agent",
instructions="""Вие сте туристически агент. Когато Ви поискат
препоръки за даден град, извлечете времето И събитията
едновременно, за да предоставите пълна консултация.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# Моделът ще извика двата инструмента паралелно за всеки град
result = await Runner.run(
agent,
"I want to visit Paris this weekend. What do you recommend?"
)
print(result.final_output)
И двата инструмента връщат JSON, което улеснява модела да комбинира отново данните. Обърнете внимание на формулировката на инструкцията: фразата “AND … simultaneously” задейства паралелното извикване, вместо мързелива верига.
Таймаути и устойчивост
API, което никога не отговаря, блокира Вашия агент също толкова сигурно, колкото и синхронен инструмент. Ограничете всяко бавно извикване с таймаут и превърнете грешките в разбираеми съобщения.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Извиква API, което може да бъде бавно."""
try:
async with asyncio.timeout(5): # 5-секунден таймаут
# Вашето API извикване тук
await asyncio.sleep(0.1) # Симулация
return f"Result for '{query}'"
except asyncio.TimeoutError:
return "The API did not respond in time. Please try again."
Производителност: Влияние на паралелизма
Нека поставим мащаба в перспектива. Три инструмента от по 500 ms, изпълнени последователно, струват 1500 ms; същите три инструмента в паралел струват около 500 ms – продължителността на най-бавния. За агент, използващ много инструменти, разликата се усеща веднага на практика.
Ключови изводи
- Използвайте
asyncза инструменти, които правят мрежови или I/O извиквания - SDK автоматично изпълнява независими инструменти паралелно
parallel_tool_calls=Falseпринуждава последователно изпълнение, когато е необходимо- Добавете таймаути с
asyncio.timeout()за устойчивост - Паралелизмът може да намали латентността с броя на инструментите