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

Arquitetura de agente: o ciclo de raciocínio-ferramenta

Aula 2 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Arquitetura de agente: o ciclo de raciocínio-ferramenta
  2. O ciclo de vida do agente
  3. Estrutura interna: itens e mensagens
  4. Chamadas paralelas vs. sequenciais
  5. O parâmetro max_turns
  6. Pontos-chave

Atualizado em 3 de novembro de 2026: Em rechercher_produit, faltavam as aspas nas chaves prix e stock, o que causava um NameError na primeira chamada da ferramenta.

Arquitetura de agente: o ciclo de raciocínio-ferramenta

Para construir agentes eficazes, precisa de compreender a sua arquitetura interna. Um agente da OpenAI opera num ciclo de raciocínio: recebe uma tarefa, pensa, utiliza uma ferramenta, observa o resultado e decide se terminou ou se precisa de continuar. Tudo o que fizer a seguir — declarar ferramentas, definir salvaguardas, orquestrar múltiplos agentes — baseia-se neste ciclo.

O ciclo de vida do agente

Cada execução segue seis passos:

  1. Receção: O agente recebe a mensagem do utilizador e as instruções do sistema
  2. Raciocínio: O modelo analisa o pedido e decide a próxima ação
  3. Chamada de ferramenta: Se necessário, o agente chama uma ou mais ferramentas
  4. Observação: O agente recebe os resultados das ferramentas
  5. Decisão: O agente decide se continua (volta ao passo 2) ou se responde
  6. Resposta: O agente produz a sua resposta final

A chave é o ciclo entre os passos 2 e 5, que pode executar-se várias vezes. Um agente pode encadear 5, 10 ou até 20 chamadas de ferramenta antes de produzir uma resposta final, sem que escreva uma única linha de código de orquestração. O exemplo abaixo ilustra isto: são declaradas duas ferramentas independentes e o modelo decide como as encadear.

from agents import Agent, Runner, function_tool

@function_tool
def rechercher_produit(nom: str) -> str:
    """Searches for a product in the catalog."""
    # Simulation - in production, call your database
    catalogue = {
        "laptop-pro": {"prix": 1299, "stock": 45},
        "tablet-air": {"prix": 599, "stock": 120},
    }
    produit = catalogue.get(nom)
    if produit:
        return f"Produit {nom}: {produit['prix']}€, stock: {produit['stock']}"
    return f"Produit {nom} non trouvé"

@function_tool
def calculer_remise(prix: float, pourcentage: float) -> str:
    """Calculates the price after discount."""
    prix_final = prix * (1 - pourcentage / 100)
    return f"Prix après {pourcentage}% de remise : {prix_final:.2f}€"

agent = Agent(
    name="Sales Agent",
    instructions="You help customers find products and calculate discounts.",
    tools=[rechercher_produit, calculer_remise],
    model="gpt-5.6-terra",
)

# The agent will: 1) find the product, 2) calculate the discount, 3) respond
result = Runner.run_sync(
    agent,
    "What is the price of the laptop-pro with a 15% discount?"
)
print(result.final_output)

A pergunta requer duas operações que não estão explicitamente ligadas no código. O agente efetua automaticamente duas chamadas de ferramenta em sequência: primeiro rechercher_produit, depois calculer_remise com o preço recuperado. Este encadeamento é uma decisão do modelo, não uma sua instrução.

Estrutura interna: itens e mensagens

A API Responses estrutura cada interação como itens. Analisá-los permite-lhe ver o que o seu agente fez realmente. Surgem três tipos na conversa:

  • message: uma mensagem de texto (do utilizador ou do agente)
  • function_call: uma chamada de ferramenta decidida pelo agente
  • function_call_output: o resultado devolvido pela ferramenta
result = Runner.run_sync(agent, "Find the tablet-air")

# Inspect the reasoning steps
for item in result.raw_responses:
    print(f"Type: {type(item).__name__}")
    # You'll see: message input → function_call → function_call_output → message output

Adote o hábito de rastrear este ciclo sempre que um agente produzir uma resposta surpreendente. Nove em cada dez vezes, a anomalia aparece num function_call com argumentos inesperados.

Chamadas paralelas vs. sequenciais

Nem todos os passos dependem uns dos outros. Quando duas chamadas são independentes, o agente pode decidir executá-las em paralelo.

@function_tool
def obtenir_meteo(ville: str) -> str:
    """Gets the current weather for a city."""
    meteos = {"Paris": "18°C, sunny", "Lyon": "16°C, cloudy"}
    return meteos.get(ville, "Data unavailable")

agent = Agent(
    name="Travel Agent",
    instructions="You help plan trips.",
    tools=[obtenir_meteo, rechercher_produit],
    model="gpt-5.6-terra",
)

# The agent will call obtenir_meteo("Paris") and obtenir_meteo("Lyon") in parallel
result = Runner.run_sync(
    agent,
    "What's the weather in Paris and Lyon?"
)

O tempo em Lyon não depende do de Paris: o SDK gere o paralelismo automaticamente e lança ambas as chamadas simultaneamente, reduzindo a latência. Compare isto com o exemplo de vendas acima, onde o cálculo do desconto teve de esperar pelo preço: aí, a sequência impõe-se.

O parâmetro max_turns

Um ciclo autónomo pode, no pior dos casos, nunca parar: o agente chama uma ferramenta, o resultado leva-o a chamar outra, e assim sucessivamente. A salvaguarda é um único parâmetro.

result = Runner.run_sync(
    agent,
    "Full catalog analysis",
    max_turns=10  # Maximum 10 loop iterations
)

Se o agente atingir o limite, para com os resultados obtidos até ao momento. Em produção, isto é uma segurança essencial: limita tanto o tempo de resposta como o custo.

Pontos-chave

  • Um agente executa num ciclo: raciocínio → ferramenta → observação → decisão
  • Este ciclo pode executar-se várias vezes antes de produzir uma resposta
  • O modelo decide automaticamente quais as ferramentas a chamar e em que ordem
  • Chamadas de ferramenta independentes são executadas em paralelo
  • max_turns limita o número de iterações por segurança