Carregando
0x60Lição 7 de 16

Retorne resultados, erros e indicações de comportamento

Escolha entre erro de protocolo e erro de execução e descreva o comportamento com anotações.

20 min Questionário com 6 perguntas 1 exercício de código
Ao final desta lição, você saberá
  • Diferenciar erros JSON-RPC de falhas durante a execução
  • Retornar conteúdo útil para o modelo
  • Configurar anotações sem tratá-las como garantias

Falhas de protocolo e falhas da ferramenta são situações diferentes:

Erro de protocoloErro ao executar a ferramenta
Exemplosferramenta desconhecida, solicitação malformadaAPI indisponível, data inválida, regra de negócio
Formatoerror JSON-RPC, como -32602resposta normal com isError: true
Chega ao modelo?pode não chegardeve chegar para permitir correção e nova tentativa

Anotações como readOnlyHint, destructiveHint, idempotentHint e openWorldHint ajudam o host a decidir quando pedir confirmação. Elas são afirmações do servidor, não provas de segurança.

Erro de execução que o modelo pode usar para corrigir a chamada
1{
2  "jsonrpc": "2.0",
3  "id": 4,
4  "result": {
5    "resultType": "complete",
6    "content": [{ "type": "text", "text": "Data de partida inválida: use uma data futura." }],
7    "isError": true
8  }
9}

Experimente

Até 15 XP

Que tipo de erro?

Classifique cada falha como erro de protocolo ou erro durante a execução da ferramenta.

0 de 5 classificadosPontuação 0/0
  • “O cliente chama a ferramenta inexistente “fly_to_moon””

  • “A data informada já passou”

  • “A API de clima excedeu o tempo limite”

  • “O corpo da solicitação não contém JSON válido”

  • “Não existe pedido com aquele número”

Indicações de comportamento: anotações

As ferramentas podem incluir anotações para ajudar o cliente a decidir o que confirmar com a pessoa usuária. Estas quatro indicações têm valores padrão cautelosos: readOnlyHint (false), destructiveHint (true), idempotentHint (false) e openWorldHint (true). As duas últimas indicações sobre efeitos destrutivos e idempotência só importam para ferramentas que não são somente de leitura. Anotações são declarações do servidor, não garantias de segurança.

Experimente

Até 15 XP

Anote as ferramentas

Configure as quatro indicações para cada ferramenta e confira suas escolhas. Pense no que acontece quando a ferramenta é executada — e no que acontece se ela for chamada duas vezes.

Ferramenta 1 de 5Indicações corretas 0/0

search_docs

Pesquisa a wiki da empresa e retorna os títulos das páginas encontradas.

readOnlyHint (padrão false)

Apenas lê — sem alterar nada?

destructiveHint (padrão true)

Pode excluir, sobrescrever ou enviar algo?

idempotentHint (padrão false)

Chamadas repetidas têm o mesmo efeito de uma só?

openWorldHint (padrão true)

Pode acessar sistemas externos ao servidor?

Principais conclusões

  • Ferramenta desconhecida e mensagem malformada geram erros JSON-RPC; falha de execução retorna isError: true.

  • Erros de execução chegam ao modelo para que ele possa corrigir a solicitação.

  • Anotações orientam confirmações, mas não devem ser aceitas sem confiança no servidor.

Quiz da aula

6 perguntas · aprovação com 5 acertos · até 50 XP

Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.

Pratique: crie um servidor MCP

Escreva código Python no editor e execute os testes com exemplos. O Python roda localmente no navegador usando WebAssembly.

Exercício 1

Reporte cada falha no formato adequado

+25 XP

Leia o tipo da falha e a mensagem, separados por |. unknown_tool e malformed são erros de protocolo; invalid_input, api_failure e business_rule são erros de execução. Imprima o código JSON-RPC ou result isError=true, conforme o caso.

  • Ferramenta desconhecida
  • Data inválida
  • Mensagem malformada
main.py
Carregando editor…

O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.

Dúvidas sobre esta lição

Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.

Carregando publicações…