Phase 13 - Lesson 23

Capstone — Construa um Ecossistema de Ferramentas Completo

A Fase 13 ensinou cada parte. Este capstone as interliga em um sistema com formato de produção: um servidor MCP com ferramentas + recursos + prompts + tarefas + UI, OAuth 2.1 na borda, um gateway RBAC, um cliente multi-servidor, uma chamada de subagente A2A, rastreamento OTel em um coletor, detecção de envenenamento de ferramentas em CI e um pacote AGENTS.md + SKILL.md. Ao final, você poderá defender cada escolha de arquitetura.

Tipo: Build Linguagens: Python (stdlib, end-to-end ecosystem harness) Pré-requisitos: Fase 13 · 01 a 21 Tempo: ~120 minutos

Objetivos de Aprendizado

• Compor um servidor MCP expondo ferramentas, recursos, prompts e uma tarefa com um aplicativo ui://.
• Proteger o servidor com um gateway OAuth 2.1 que impõe RBAC e hashes fixados.
• Escrever um cliente multi-servidor que realiza rastreamento com atributos GenAI do OTel de ponta a ponta.
• Delegar parte de uma carga de trabalho a um subagente A2A; verificar se a opacidade é preservada.
• Empacotar toda a stack com AGENTS.md + SKILL.md para que outros agentes possam executá-la.

O Problema

Entregar o sistema de "pesquisa e relatório":

• O usuário pergunta: "summarize the three most-cited 2026 arXiv papers on agent protocols."
• O sistema: pesquisa no arXiv via MCP; delega a sumarização do artigo para um agente escritor especializado via A2A; agrega os resultados; renderiza um relatório interativo como um recurso do MCP Apps ui://; registra cada etapa no OTel.

Todas as primitivas da Fase 13 aparecem aqui. Isso não é um brinquedo — sistemas de assistência de pesquisa em produção lançados em 2026 pela Anthropic (o produto Claude Research), OpenAI (GPTs com SDK do Apps) e terceiros têm exatamente esse formato.

O Conceito

Architecture

[user] -> [client] -> [gateway (OAuth 2.1 + RBAC)] -> [research MCP server]
                                                      |
                                                      +- MCP tool: arxiv_search (pure)
                                                      +- MCP resource: notes://recent
                                                      +- MCP prompt: /research_topic
                                                      +- MCP task: generate_report (long)
                                                      +- MCP Apps UI: ui://report/current
                                                      +- A2A call: writer-agent (tasks/send)
                                                      |
                                                      +- OTel GenAI spans

Trace hierarchy

agent.invoke_agent
 ├── llm.chat (kick off)
 ├── mcp.call -> tools/call arxiv_search
 ├── mcp.call -> resources/read notes://recent
 ├── mcp.call -> prompts/get research_topic
 ├── a2a.tasks/send -> writer-agent
 │    └── task transitions (opaque internals)
 ├── mcp.call -> tools/call generate_report (task-augmented)
 │    └── tasks/status polling
 │    └── tasks/result (completed, returns ui:// resource)
 └── llm.chat (final synthesis)

Um trace id. Cada span possui os atributos gen_ai.* corretos.

Postura de segurança

• OAuth 2.1 + PKCE com indicador de recurso fixando a audiência no gateway.
• O gateway armazena as credenciais upstream; o usuário nunca as vê.
• RBAC: alice tem research:read, research:write, pode chamar todas as ferramentas. bob tem research:read, não pode chamar generate_report.
• Manifesto de descrição fixado: rejeita qualquer servidor cujos hashes de ferramentas tenham mudado.
• Auditoria "Rule of Two": nenhuma ferramenta combina entrada não confiável, dados confidenciais e ação consequente.

Renderização

A tarefa final generate_report retorna blocos de conteúdo mais um recurso ui://report/current. O host do cliente (Claude Desktop, etc.) renderiza o painel interativo em um iframe sandbox. O painel contém uma lista ordenada de artigos, contagem de citações e um botão que chama host.callTool('summarize_paper', {arxiv_id}) para qualquer artigo que o usuário clicar.

Empacotamento

Tudo é entregue como:

research-system/
  AGENTS.md                     # project conventions
  skills/
    run-research/
      SKILL.md                  # the top-level workflow
  servers/
    research-mcp/               # the MCP server
      pyproject.toml
      src/
  agents/
    writer/                     # the A2A agent
  gateway/
    config.yaml                 # RBAC + pinned manifest

Os usuários implantam com docker compose up. Usuários do Claude Code, Cursor, Codex e opencode podem executar o sistema invocando a skill run-research.

O que cada lição da Fase 13 contribuiu

Use It

O arquivo code/main.py costura os padrões das lições anteriores em uma demonstração executável. Tudo usando stdlib, tudo em processo para que você possa ler de ponta a ponta. Ele executa o fluxo completo para o cenário de pesquisa e relatório: handshake com gateway, simulação de OAuth 2.1, mesclagem de tools/list, generate_report como uma tarefa, chamada A2A para writer, recurso ui:// retornado, spans do OTel emitidos.

O que observar:

• Um trace id em cada salto.
• A política do gateway bloqueia a gravação por parte de um segundo usuário.
• O ciclo de vida da tarefa vai de working → completed e retorna tanto texto quanto o conteúdo ui://.
• O estado interno da chamada A2A é opaco para o orquestrador.
• AGENTS.md e SKILL.md são os únicos arquivos de que outro agente precisa para reproduzir o fluxo de trabalho.

Ship It

Esta lição produz outputs/skill-ecosystem-blueprint.md. Dada uma necessidade de produto (pesquisa, sumarização, automação), a skill produz a arquitetura completa: quais primitivas do MCP, quais controles de gateway, quais chamadas A2A, qual telemetria, qual empacotamento.

Exercícios

1. Execute code/main.py. Observe o trace id único e como os spans se aninham. Conte quantas primitivas da Fase 13 a demonstração acessa.

2. Estenda a demonstração: adicione um segundo servidor MCP de backend (por exemplo, bibliography) e confirme que o gateway mescla suas ferramentas no mesmo namespace.

3. Substitua o agente escritor A2A simulado por um real sendo executado em um subprocesso. Use o harness da Lição 19.

4. Adicione uma etapa de redação de PII no gateway de roteamento entre o orquestrador e o LLM. Confirme que os e-mails na consulta do usuário são limpos.

5. Escreva um AGENTS.md para um colega de equipe que manterá este sistema. Deve levar menos de fins de cinco minutos para ler e fornecer tudo o que ele precisa para rodar o capstone no Cursor ou Codex.

Key Terms

Further Reading

• MCP — Specification 2025-11-25 — referência consolidada
• MCP blog — 2026 roadmap — para onde o protocolo está caminhando
• a2a-protocol.org — referência do A2A v1.0
• OpenTelemetry — GenAI semconv — convenções canônicas de rastreamento
• Anthropic — Claude Agent SDK overview — padrões de runtime de agentes em produção