Programação Agéntica com Chamada de Ferramentas
Nesta página
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