Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Ferramentas Assíncronas e Paralelas

Aula 8 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Ferramentas Assíncronas e Paralelas
  2. Ferramentas Assíncronas
  3. Paralelismo Automático
  4. Controlo do Paralelismo
  5. Padrão: Agregação de Resultados Paralelos
  6. Timeouts e Resiliência
  7. Desempenho: Impacto do Paralelismo
  8. Pontos-chave

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 async para ferramentas que fazem chamadas de rede ou I/O
  • O SDK executa automaticamente ferramentas independentes em paralelo
  • parallel_tool_calls=False forç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