Arquitetura de agente: o ciclo de raciocínio-ferramenta
Nesta página
Atualizado em 3 de novembro de 2026: Em
rechercher_produit, faltavam as aspas nas chavesprixestock, o que causava umNameErrorna 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:
- Receção: O agente recebe a mensagem do utilizador e as instruções do sistema
- Raciocínio: O modelo analisa o pedido e decide a próxima ação
- Chamada de ferramenta: Se necessário, o agente chama uma ou mais ferramentas
- Observação: O agente recebe os resultados das ferramentas
- Decisão: O agente decide se continua (volta ao passo 2) ou se responde
- 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 agentefunction_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_turnslimita o número de iterações por segurança