MÓDULO 1.2

▶️ Execução de ferramentas

Valide argumentos, aplique políticas e execute tools com timeout, cancelamento e respostas estruturadas.

6

Tópicos

3h

Carga

Agent Developer

Nível

Runtime

Tipo

0 de 60%
1

Separe proposta de execução

O que é: A chamada produzida pelo modelo é uma proposta não confiável até passar por validação e política.

Por que aprender: A fronteira impede que texto probabilístico se transforme diretamente em efeito.

Chamada proposta estado de partida Policy + execução decisão observável Resultado observado resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

const proposal = await model.chooseTool(context);
const approved = await gate.evaluate(proposal, session);
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

tool call

02

untrusted input

03

policy gate

04

execução

2

Valide o schema novamente

O que é: Mesmo quando o provedor aplica schemas, o runtime valida tipos, limites, enums e campos extras.

Por que aprender: Defesa em profundidade contém divergências de provider e chamadas produzidas por código externo.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
const result = validator.validate(tool.inputSchema, proposal.arguments);
if (!result.ok) return fail("INVALID_ARGUMENTS", result.errors);
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

JSON Schema

02

coerção proibida

03

limites

04

erro estável

3

Aplique política antes do efeito

O que é: Risco, autenticação, escopo e necessidade de confirmação são decididos fora do modelo.

Por que aprender: O LLM pode recomendar; a aplicação continua responsável por autorizar.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

if (tool.annotations?.destructiveHint) {
  await requireHumanConfirmation(proposal);
}
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

autorização

02

risco

03

confirmação

04

escopo

4

Execute com orçamento e cancelamento

O que é: Toda execução recebe AbortSignal, deadline e limites compatíveis com a experiência.

Por que aprender: Uma conversa abandonada não deve manter rede, UI ou backend trabalhando indefinidamente.

CÓDIGO DE REFERÊNCIA

const signal = AbortSignal.any([turn.signal, AbortSignal.timeout(10_000)]);
const tools = await document.modelContext.getTools();
const tool = tools.find((item) => item.name === proposal.name);
if (!tool) throw new Error("Tool não está mais disponível");
return document.modelContext.executeTool(tool, proposal.arguments, { signal });
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

AbortSignal

02

deadline

03

resource budget

04

cleanup

5

Normalize resultados e falhas

O que é: O runtime converte retornos heterogêneos em envelopes com status, dados, evidência e próxima ação.

Por que aprender: Uma forma comum simplifica o loop sem esconder o erro original.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

return { ok: false, code: "AUTH_REQUIRED", recovery: { action: "request_login" } };
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

envelope

02

erro recuperável

03

evidência

04

next action

6

Registre um rastro reproduzível

O que é: Cada execução liga turno, catálogo, proposta, decisão de política, duração e resultado sanitizado.

Por que aprender: O rastro permite depurar seleção, execução e efeito sem gravar segredos.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Implementar um executor que recebe uma chamada do modelo, valida a intenção e devolve envelope de sucesso, erro ou recuperação.

Critério de Agent Developer responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

trace.record({ turnId, tool: proposal.name, policy: approved.reason, durationMs, outcome });
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

traceId

02

catalog version

03

latência

04

redaction

📦 Entrega do módulo

Implementar um executor que recebe uma chamada do modelo, valida a intenção e devolve envelope de sucesso, erro ou recuperação.

Critério de aceite

A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.

Evidência

Inclua código, cenário testado, resultado observado e uma limitação conhecida.

← Voltar para a trilhaPróximo módulo: 1.3 →

Fontes técnicas