Ferramentas Assíncronas e Paralelas
Nesta página
Ferramentas Assíncronas e Paralelas
Em produção, as suas ferramentas chamam APIs externas, consultam bases de dados ou realizam operações de I/O. Estas operações demoram tempo, e esse tempo acumula-se: um agente que encadeia cinco chamadas de um segundo leva cinco segundos a responder. Tornar as ferramentas assíncronas e aproveitar o paralelismo nativo do SDK é o que separa uma demonstração de um serviço utilizável.
Ferramentas Assíncronas
O decorador @function_tool suporta nativamente funções async. Não é necessária qualquer configuração: declare async def, utilize um cliente HTTP assíncrono e o SDK trata do resto.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Pesquisa informações sobre a empresa através da 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"Empresa: {data['name']}, SIREN: {data['siren']}, Faturamento: {data['revenue']}"
return f"Sem resultados para '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Verifica a solvabilidade de uma empresa pelo seu número 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"Pontuação de solvabilidade: {data['score']}/100, risco: {data['risk_level']}"
Quando o Runner executa uma ferramenta assíncrona, não bloqueia o loop de eventos. Num servidor FastAPI, isto significa que outros pedidos continuam a ser processados enquanto o seu agente aguarda a resposta da API Societe.com.
Paralelismo Automático
Duas ferramentas assíncronas independentes podem ser executadas simultaneamente. O modelo decide isto, e as suas instruções podem incentivar explicitamente este comportamento.
from agents import Agent, Runner
agent = Agent(
name="Analista B2B",
instructions="""Você analisa empresas para decisões de negócios.
Quando solicitado a analisar uma empresa, recupere as suas informações
E verifique a sua solvabilidade ao mesmo tempo.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# O modelo lançará ambas as ferramentas em paralelo
result = await Runner.run(
agent,
"Analise a empresa Acme Corp (SIREN 123456789)"
)
Como o SIREN é fornecido no pedido, a verificação de solvabilidade não espera pela pesquisa da empresa: o SDK executa ambas as chamadas simultaneamente. O tempo total equivale à duração da ferramenta mais lenta, e não à soma de ambas.
Controlo do Paralelismo
O paralelismo nem sempre é desejável. Se as suas ferramentas escreverem no mesmo registo ou se a ordem for importante para a consistência dos dados, force a execução sequencial.
from agents import Agent
agent = Agent(
name="Agente Cauteloso",
instructions="Execute as ferramentas uma por uma para garantir a consistência dos dados.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Força a execução sequencial
)
O parâmetro parallel_tool_calls=False força o modelo a chamar apenas uma ferramenta de cada vez. Você troca latência por previsibilidade.
Padrão: Agregação de Resultados Paralelos
O caso prático mais comum envolve a recolha de dados de múltiplas fontes para a mesma entidade. Aqui, o clima de uma cidade e a sua agenda cultural não têm relação entre si, mas a resposta necessita de ambos.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Obtém o clima atual para uma cidade."""
# Simulação - em produção: chamada à API de meteorologia
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:
"""Obtém eventos futuros numa cidade."""
events = {
"Paris": ["Concerto no Stade de France", "Exposição no Louvre"],
"Lyon": ["Festival das Luzes", "Feira da Gastronomia"],
"Marseille": ["Regata do Mediterrâneo"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Agente de Viagens",
instructions="""Você é um agente de viagens. Quando solicitado
por recomendações para uma cidade, recupere o clima E os eventos
simultaneamente para fornecer um conselho completo.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# O modelo chamará ambas as ferramentas em paralelo para cada cidade
result = await Runner.run(
agent,
"Quero visitar Paris neste fim de semana. O que recomenda?"
)
print(result.final_output)
Ambas as ferramentas devolvem JSON, o que facilita ao modelo recombinar os dados. Note a formulação da instrução: o “E … simultaneamente” desencadeia a chamada paralela em vez de uma cadeia preguiçosa.
Timeouts e Resiliência
Uma API que nunca responde bloqueia o seu agente tão seguramente quanto uma ferramenta síncrona. Limite cada chamada lenta com um timeout e transforme as falhas em mensagens inteligíveis.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Chama uma API que pode ser lenta."""
try:
async with asyncio.timeout(5): # Timeout de 5 segundos
# A sua chamada à API aqui
await asyncio.sleep(0.1) # Simulação
return f"Resultado para '{query}'"
except asyncio.TimeoutError:
return "A API não respondeu a tempo. Por favor, tente novamente."
Desempenho: Impacto do Paralelismo
Vamos colocar a escala em perspetiva. Três ferramentas de 500 ms executadas sequencialmente custam 1500 ms; as mesmas três ferramentas em paralelo custam cerca de 500 ms — a duração da mais lenta. Para um agente que utiliza muitas ferramentas, a diferença é imediatamente percetível na prática.
Pontos-chave
- Utilize
asyncpara ferramentas que fazem chamadas de rede ou I/O - O SDK executa automaticamente ferramentas independentes em paralelo
parallel_tool_calls=Falseforça a execução sequencial quando necessário- Adicione timeouts com
asyncio.timeout()para resiliência - O paralelismo pode dividir a latência pelo número de ferramentas