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

Programação Agéntica com Chamada de Ferramentas

Aula 6 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O que é a programação agéntica?
  2. O ciclo agéntico
  3. Exemplo prático: correção de um erro
  4. Utilização de ferramentas na prática
  5. Ciclo agéntico de várias voltas
  6. Pontos-chave

Lição atualizada em 2 de novembro de 2026. Os exemplos originais utilizavam o Devstral, que foi removido da API em 31 de julho de 2026. Passaram agora a utilizar o Mistral Small 4 (mistral-small-2603), e o ciclo agéntico segue o modelo da documentação da Mistral (todas as chamadas de ferramentas numa resposta são processadas até à resposta final). Fonte: Function calling.

O que é a programação agéntica?

A programação agéntica altera a natureza do que pede ao modelo para fazer. Em vez de solicitar um excerto de código, depois outro, depois um terceiro, e os juntar manualmente, atribui uma tarefa completa. O modelo resolve-a encadeando os passos autonomamente: exploração, planeamento, implementação e verificação. Mantém-se o decisor sobre o que precisa de ser feito, mas deixa de microgerir cada movimento.

Os modelos Devstral foram construídos para este fluxo de trabalho; os modelos de propósito geral atuais, liderados pelo Mistral Small 4, gerem-no através da chamada de ferramentas. Um agente não se limita a responder a uma pergunta; atua sobre o repositório.

O ciclo agéntico

Fase 1 — Compreender

O agente começa sempre por se orientar. Lê a estrutura de pastas e ficheiros, identifica os ficheiros relevantes para a tarefa solicitada, rastreia as dependências entre módulos para perceber o que uma alteração pode afetar e regista as convenções existentes — nomenclatura, organização de testes e padrões recorrentes. Esta fase parece improdutiva porque não escreve código, mas determina se o código resultante parecerá seu ou de um estranho.

Fase 2 — Planear

Antes de escrever uma única linha, o agente formula um plano. Divide a tarefa em subtarefas ordenadas, distingue os ficheiros a modificar dos que deve criar, antecipa efeitos secundários e riscos de regressão e define uma abordagem técnica. É neste momento que a sua intervenção é mais barata: corrigir um plano demora trinta segundos; corrigir dez ficheiros que já escreveu demora muito mais tempo.

Fase 3 — Executar

A implementação desenrola o plano passo a passo. O agente edita ficheiros existentes, cria novos quando a estrutura o exige, atualiza importações e dependências deslocadas pelas suas alterações e ajusta ficheiros de configuração ao longo do processo. A consistência nestas alterações é exatamente aquilo que um modelo de completamento não consegue garantir.

Fase 4 — Verificar

Finalmente, chega a prova de que o trabalho se mantém. O agente executa a suíte de testes existente, escreve novos testes para o código que acabou de adicionar, garante que a compilação passa e revê o seu próprio diff à procura de erros ou modificações inadvertidas. Um agente que salte esta fase produz código plausível, não código correto.

Exemplo prático: correção de um erro

Suponha que diz ao agente: «Os utilizadores recebem um erro 500 quando submetem um formulário com um e-mail contendo um ’+’». O ciclo assume então esta forma:

1. COMPREENDER
   -> Procurar ficheiros relacionados com o formulário (pesquisar "email" no código)
   -> Ler o controlador que gere a submissão
   -> Ler a função de validação de e-mail
   -> Identificar a expressão regular que rejeita '+'

2. PLANEAR
   -> Modificar a expressão regular de validação para aceitar '+'
   -> Adicionar um teste unitário para e-mails com '+'
   -> Verificar se nenhuma outra parte do código filtra o '+'

3. EXECUTAR
   -> Modificar src/validators/email.py: corrigir o padrão da expressão regular
   -> Criar tests/test_email_validation.py: adicionar casos com '+'
   -> Modificar src/controllers/form.py: adicionar um registo para depuração

4. VERIFICAR
   -> Executar pytest -> todos os testes passam
   -> Verificar diff -> as alterações são consistentes e mínimas

Repare na terceira linha do plano: o agente não se limita a corrigir onde o erro se manifesta; verifica se nenhum outro filtro rejeita o carácter noutro local. Esta procura da causa raiz, em vez de apenas do sintoma, é o que distingue uma correção agéntica de um remendo pontual.

Utilização de ferramentas na prática

O agente atua no seu ambiente através de chamadas de funções. Declara as ferramentas disponíveis no pedido, incluindo o seu nome, descrição e esquema de parâmetros; o modelo escolhe quais chamar e com que argumentos.

# Exemplo de uma conversa agéntica
messages = [
    {
        "role": "user",
        "content": "Adicione validação de palavra-passe forte ao módulo de autenticação."
    }
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Ler o conteúdo de um ficheiro do projeto",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "Caminho do ficheiro"}
                },
                "required": ["path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "Escrever ou modificar um ficheiro do projeto",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                    "content": {"type": "string"}
                },
                "required": ["path", "content"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_command",
            "description": "Executar um comando de shell",
            "parameters": {
                "type": "object",
                "properties": {
                    "command": {"type": "string"}
                },
                "required": ["command"]
            }
        }
    }
]

response = client.chat.complete(
    model="mistral-small-2603",
    messages=messages,
    tools=tools,
    tool_choice="auto",   # valor predefinido: o modelo decide se chama uma ferramenta
)

Para este pedido, a sequência típica começa com read_file("src/auth/validators.py") para compreender o código existente, continua com read_file("tests/test_auth.py") para ver o formato dos testes atuais, passando depois à escrita: write_file("src/auth/validators.py", ...) com a regra de validação adicionada, write_file("tests/test_auth.py", ...) com os novos casos e, finalmente, run_command("pytest tests/test_auth.py") para verificar. A ordem importa: ao abrir ambos os ficheiros antes de tocar num único carácter, o agente capta as suas convenções e reproduz-as, em vez de importar outras que tenha visto noutro lugar.

Ciclo agéntico de várias voltas

Nada disto acontece numa única chamada. O coração da programação agéntica é o ciclo de várias voltas: o modelo propõe uma ação, o seu código executa-a e envia o resultado de volta para que possa decidir o próximo passo. Mantém o controlo da execução real, o que também serve como sua barreira de segurança.

import json

TOOLS = {"read_file": read_file, "write_file": write_file, "run_command": run_command}

response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
messages.append(response.choices[0].message)

for _ in range(30):   # barreira de segurança: um agente nunca deve entrar em loop infinito
    tool_calls = response.choices[0].message.tool_calls
    if not tool_calls:
        break         # sem mais chamadas de ferramentas: a resposta final chegou
    for tool_call in tool_calls:   # uma resposta pode conter várias chamadas
        name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        result = TOOLS[name](**arguments)
        messages.append({
            "role": "tool",
            "name": name,
            "content": str(result),
            "tool_call_id": tool_call.id,
        })
    response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
    messages.append(response.choices[0].message)

print(response.choices[0].message.content)

Três detalhes são importantes. A mensagem do agente e cada resultado de ferramenta são reinjetados no histórico, emparelhados pelo tool_call_id: omita um ou outro e o agente perde o fio à meada, recordando as mesmas ferramentas num ciclo. Uma única resposta pode conter várias chamadas de ferramentas, já que as chamadas paralelas são permitidas por predefinição (parallel_tool_calls=False proíbe-as): processe-as todas. Por fim, limite o número de voltas e faça com que um humano valide os comandos de shell e as escritas em ficheiros: um agente que executa tudo o que propõe é um risco, não uma poupança de tempo.

Pontos-chave

  • A programação agéntica segue um ciclo: compreender, planear, executar, verificar
  • O agente atua no repositório através da chamada de ferramentas (tools, tool_choice)
  • O ciclo de várias voltas permite ao agente iterar até à resolução completa
  • O agente modifica vários ficheiros de forma consistente numa única tarefa
  • A fase de verificação (testes, compilação) é essencial para a fiabilidade