Agente multifase com ciclo de raciocínio
Nesta página
Agente multifase com ciclo de raciocínio
Os agentes mais poderosos não param após uma única chamada de ferramenta. Eles encadeiam múltiplos passos de raciocínio, ajustam a sua estratégia com base nos resultados e iteram até alcançarem o seu objetivo. Nesta lição, vai aprender a construir estes agentes multifase. Os exemplos utilizam a família GPT-5.6: onde a geração anterior exigia a troca de modelos para ativar o raciocínio, agora controla este comportamento através da definição de esforço no modelo escolhido.
O padrão planear-executar
Um agente multifase começa por criar um plano e, em seguida, executa cada passo. Esta separação é deliberada: o planeador não tem ferramentas e produz uma estrutura tipada, enquanto o executor recebe este plano como um roteiro e simplesmente segue-o. Um pedido vago como «preparar a revisão trimestral para contas chave» transforma-se numa sequência concreta de ações — consultar o CRM, gerar o relatório, enviar o e-mail — antes de qualquer ação ser tentada.
from agents import Agent, Runner, function_tool
from pydantic import BaseModel
import json
class PlanAction(BaseModel):
steps: list[str]
objective: str
planner_agent = Agent(
name="Planner",
instructions="""You receive a complex task. Break it down into simple, ordered steps.
Each step must be a concrete, actionable item.""",
model="gpt-5.6-sol", # Advanced reasoning for planning
output_type=PlanAction,
)
@function_tool
def search_crm(query: str) -> str:
"""Searches the CRM for customer information."""
return json.dumps({"customers": [
{"name": "Acme Corp", "revenue": 500000, "contract": "Enterprise"},
{"name": "TechStart", "revenue": 50000, "contract": "Starter"},
]})
@function_tool
def generate_report(title: str, content: str) -> str:
"""Generates a formatted report."""
return f"Report '{title}' generated successfully ({len(content)} characters)"
@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
"""Sends an email."""
return f"Email sent to {recipient}: {subject}"
executor_agent = Agent(
name="Executor",
instructions="""You execute tasks step by step.
Use available tools to complete each step.
If a step fails, try an alternative approach.""",
tools=[search_crm, generate_report, send_email],
model="gpt-5.6-terra",
)
async def process_complex_task(task: str):
# Step 1: Plan
plan = await Runner.run(planner_agent, task)
print(f"Plan: {plan.final_output.steps}")
# Step 2: Execute with the plan as context
execution_instructions = f"""Execute the following steps in order:
{chr(10).join(f'{i+1}. {e}' for i, e in enumerate(plan.final_output.steps))}
Objective: {plan.final_output.objective}"""
result = await Runner.run(executor_agent, execution_instructions)
return result.final_output
Agente de autocorreção
Planear não é suficiente: no mundo real, as ferramentas falham. A segunda forma de ciclo permite que o agente detete os seus próprios erros e os corrija. Tudo depende de um detalhe frequentemente negligenciado: a ferramenta não lança uma exceção; devolve uma mensagem de erro legível. O agente lê-a, percebe que esqueceu a cláusula FROM, reescreve a sua consulta e tenta novamente, dentro do limite de três tentativas definido nas suas instruções.
from agents import Agent, Runner, function_tool
@function_tool
def execute_sql_query(sql: str) -> str:
"""Executes an SQL query on the database."""
# Simulation: some queries fail
if "DROP" in sql.upper():
return "ERROR: Destructive queries are forbidden."
if "SELECT" in sql.upper() and "FROM" not in sql.upper():
return "ERROR: Invalid SQL syntax - missing FROM."
return json.dumps({
"columns": ["name", "monthly_revenue", "region"],
"rows": [
["Acme Corp", 45000, "Île-de-France"],
["TechStart", 12000, "Rhône-Alpes"],
],
"result_count": 2
})
analyst_agent = Agent(
name="Data Analyst",
instructions="""You analyze data by executing SQL queries.
If a query fails:
1. Analyze the error message
2. Correct the query
3. Retry
Maximum 3 attempts per query.
Never use DROP, DELETE, or TRUNCATE.""",
tools=[execute_sql_query],
model="gpt-5.6-terra",
max_turns=10, # Enough turns for corrections
)
result = Runner.run_sync(
analyst_agent,
"What is the total revenue by region?"
)
Note que a proibição de consultas destrutivas aparece em dois locais: nas instruções e no código da ferramenta. A instrução guia o modelo, mas apenas a verificação no lado do servidor na ferramenta garante que um DROP TABLE nunca passe despercebido.
Padrão: cadeia de agentes especializados
Para fluxos de trabalho complexos, encadeie vários agentes especializados em vez de sobrecarregar um único agente com todas as responsabilidades. Cada elo tem um papel claro: o coletor reúne a matéria-prima, o analista — equipado com um modelo de raciocínio — identifica tendências e o redator formata a saída. O benefício é tanto educativo como operacional: quando o relatório final dececiona, sabe imediatamente qual dos três agentes corrigir.
from agents import Agent, Runner
collection_agent = Agent(
name="Data Collector",
instructions="Collect all data necessary for the analysis.",
tools=[search_crm, execute_sql_query],
model="gpt-5.6-terra",
)
analysis_agent = Agent(
name="Analyst",
instructions="Analyze the collected data and identify trends.",
model="gpt-5.6-sol", # Advanced reasoning for analysis
)
writing_agent = Agent(
name="Writer",
instructions="""Write a clear, structured report in English
based on the provided analysis. Format: introduction, key points, recommendations.""",
model="gpt-5.6-terra",
)
async def analysis_pipeline(question: str):
# Step 1: Collect data
data = await Runner.run(collection_agent, question)
# Step 2: Analyze
analysis = await Runner.run(
analysis_agent,
f"Analyze this data: {data.final_output}"
)
# Step 3: Write the report
report = await Runner.run(
writing_agent,
f"Write a report based on this analysis: {analysis.final_output}"
)
return report.final_output
Controlo da profundidade do raciocínio
Todos estes ciclos partilham uma característica: podem nunca parar. O parâmetro max_turns é a sua principal salvaguarda e deve ajustá-lo com base na ambição da tarefa. Três voltas são suficientes para um agente que se espera responda à primeira tentativa; vinte e cinco são necessárias para uma exploração que consulta múltiplas fontes antes de concluir.
# Conservative agent: few turns
simple_agent = Agent(
name="Simple Agent",
instructions="Answer in a single turn if possible.",
model="gpt-5.6-terra",
)
result = await Runner.run(simple_agent, "Simple question", max_turns=3)
# Complex agent: many turns
research_agent = Agent(
name="Deep Researcher",
instructions="Explore all angles before concluding.",
tools=[search_crm, execute_sql_query],
model="gpt-5.6-terra",
)
result = await Runner.run(research_agent, "Complete Q1 analysis", max_turns=25)
Defina este valor observando os seus registos de execução em vez de adivinhar: se as suas execuções reais terminarem em seis voltas, um limite de vinte e cinco não protege contra nada.
Pontos-chave
- O padrão planear-executar separa o planeamento (modelo de raciocínio) da execução
- Um agente de autocorreção analisa os seus erros e ajusta a sua estratégia
- Cadeias de agentes especializados permitem fluxos de trabalho complexos e sustentáveis
max_turnscontrola a profundidade do raciocínio e protege contra ciclos infinitos- Reserve capacidades de raciocínio avançado para o planeamento e a análise