Observabilidade distribuída em aplicações com A2A e MCP#
Enquanto desenvolvia aplicações compostas por vários agentes, encontrei uma dificuldade recorrente de observabilidade. Uma solicitação começava em um orquestrador, seguia para outro agente por A2A, passava por um serviço MCP e retornava ao processo inicial. Cada componente produzia telemetria, mas reconstruir a execução completa exigia correlacionar horários, logs e identificadores de negócio.
Esse tipo de arquitetura amplia os limites de uma operação. O fluxo pode atravessar processos, serviços e protocolos diferentes, embora continue representando uma única solicitação para quem utiliza o sistema. Quando o contexto de tracing se perde em alguma dessas transições, os spans seguintes passam a pertencer a outros traces e a investigação fica fragmentada.
Propagação de contexto entre os serviços#
O W3C Trace Context fornece um formato padronizado para transportar a identidade do trace. O serviço que inicia uma chamada injeta os cabeçalhos e , e o serviço receptor utiliza essas informações ao criar seus próprios spans. Dessa forma, a relação entre as operações permanece disponível para qualquer backend compatível com OpenTelemetry.
A aplicação desse mecanismo em A2A e MCP depende dos pontos de extensão oferecidos por seus respectivos SDKs. No A2A Python SDK, o contexto precisa acompanhar as chamadas do cliente e ser recuperado pelo handler do servidor. No MCP, a implementação atual utiliza as fronteiras HTTP públicas do cliente e da aplicação ASGI criada pelo servidor.
Durante esse trabalho, procurei evitar dependência de detalhes internos dos SDKs. Os adaptadores utilizam interfaces públicas e delegam o comportamento para os objetos originais. Isso reduz o impacto de atualizações e permite que a instrumentação seja acrescentada a uma aplicação existente sem substituir sua implementação de negócio.
O a2a-otel-kit#
Organizei essa implementação no projeto a2a-otel-kit, uma biblioteca Python distribuída pelo PyPI sob licença MIT. Ela reúne configuração de OpenTelemetry, exportação OTLP/HTTP, propagação W3C Trace Context, eventos JSON estruturados e adaptadores específicos para A2A e MCP.
A integração A2A cobre chamadas de cliente e servidor nos transportes JSON-RPC e REST. A integração MCP cobre Streamable HTTP por meio de um transporte HTTP instrumentado no cliente e de um middleware ASGI no servidor. As duas integrações criam spans de cliente e servidor, propagam o contexto existente e preservam o comportamento das chamadas originais, incluindo exceções, cancelamentos e encerramento antecipado de streams.
O ciclo de vida da instrumentação também é explícito. Cada instância possui seus próprios recursos e oferece operações de e . A configuração desabilitada produz spans inativos, permitindo que a aplicação utilize o mesmo código nos ambientes com ou sem tracing.
A exportação utiliza OTLP/HTTP, deixando a escolha do backend para a aplicação. O ambiente de demonstração usa Grafana Tempo, mas o tráfego pode ser encaminhado por um OpenTelemetry Collector para outros destinos compatíveis. A biblioteca não inclui SDKs específicos de fornecedores.
Tratamento dos dados de telemetria#
A instrumentação foi desenhada para registrar metadados operacionais com cardinalidade controlada. Os spans dos adaptadores utilizam nomes fixos, tipos de operação conhecidos e uma lista restrita de atributos. Chaves relacionadas a senhas, tokens, cookies, autorização e credenciais são descartadas pelo sanitizador.
Os adaptadores não leem prompts, respostas de modelos, mensagens A2A, conteúdos de tasks ou artifacts, argumentos e resultados MCP, corpos HTTP ou valores arbitrários de cabeçalhos. Em caso de falha, o span recebe o estado correspondente, mas a mensagem da exceção não é copiada para a telemetria produzida pelos adaptadores.
Essa decisão veio de uma preocupação prática. Em aplicações que processam dados pessoais, documentos ou informações comerciais, copiar o conteúdo das interações para uma plataforma de observabilidade cria uma nova superfície de armazenamento e acesso. Para este projeto, os detalhes necessários para análise funcional devem permanecer nos sistemas responsáveis por esses dados.
A API permite que a aplicação crie seus próprios spans e eventos. Nesses casos, cabe ao código consumidor decidir quais informações são apropriadas, sempre passando pelos controles de atributos disponíveis na biblioteca.
Verificação com uma execução completa#
O repositório contém uma demonstração local formada por um orquestrador, um agente A2A de análise de risco e um serviço MCP de dados. O ambiente inclui OpenTelemetry Collector, Grafana Tempo e Grafana, com todas as configurações necessárias para executar o fluxo em contêineres.
Na execução documentada, a solicitação gera 11 spans distribuídos entre os três serviços. Os spans de cliente e servidor A2A permanecem no mesmo trace, e as chamadas MCP iniciadas pelo agente continuam usando esse contexto. O resultado pode ser inspecionado no Grafana, onde a árvore mostra a sequência completa da operação.
Além da inspeção visual, um script verifica os dados armazenados no Tempo. Ele procura os spans esperados, compara seus e pesquisa um identificador privado inserido propositalmente na resposta de negócio. A execução só é considerada válida quando os spans pertencem ao mesmo trace e o identificador está ausente da telemetria.
Limites atuais#
A versão atual concentra-se nas integrações que puderam ser testadas de ponta a ponta. No A2A, a continuidade foi verificada para JSON-RPC e REST. Chamadas originadas por gRPC ainda produzem spans, mas a propagação do contexto nesse transporte permanece sem verificação.
No MCP, o suporte está limitado a Streamable HTTP. O transporte stdio possui características diferentes e não expõe a mesma fronteira HTTP utilizada pelos adaptadores. O SSE legado também ficou fora do escopo.
O projeto cuida da instrumentação e do envio por OTLP. Configuração de produção do Collector, retenção, amostragem, autenticação do backend e escalabilidade pertencem à infraestrutura da aplicação consumidora.
Próximos passos#
Pretendo testar a biblioteca em outros arranjos de agentes e acompanhar a evolução dos SDKs oficiais. Entre os temas que ainda merecem trabalho estão a continuidade A2A por gRPC, outros contextos de implantação MCP e exemplos com frameworks de orquestração de agentes.
O código, a documentação e a demonstração estão disponíveis em:
GitHub: https://github.com/brunovicco/a2a-otel-kit PyPI: https://pypi.org/project/a2a-otel-kit/
Comentários sobre a API, os pontos de instrumentação e experiências de observabilidade em sistemas distribuídos de agentes serão úteis para orientar as próximas versões.