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

Agente multifase com ciclo de raciocínio

Aula 15 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Agente multifase com ciclo de raciocínio
  2. O padrão planear-executar
  3. Agente de autocorreção
  4. Padrão: cadeia de agentes especializados
  5. Controlo da profundidade do raciocínio
  6. Pontos-chave

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_turns controla a profundidade do raciocínio e protege contra ciclos infinitos
  • Reserve capacidades de raciocínio avançado para o planeamento e a análise