Visão geral

Um único processo

O mcpd faz duas coisas com um único processo. Ele segura uma execução durável entre as etapas dela: o cursor, as repetições, os temporizadores e as esperas, enquanto o seu próprio código, em qualquer linguagem, faz o trabalho dentro de cada etapa. E ele recebe o que o seu agente fez, guarda, e devolve para você como execuções que dá para ler. É um binário só, com o SQLite ligado dentro dele. Não há banco de dados para subir, não há coletor para rodar ao lado e não há conta em lugar nenhum.

O daemon escuta na porta 4317 e serve cinco coisas a partir dessa única porta:

• Ingestão OTLP em /v1/traces, /v1/logs e /v1/metrics, então uma instalação de OpenTelemetry que já existe não precisa de código novo.
• Ingestão nativa em /v1/ingest, que carrega as partes do modelo para as quais o OTLP não tem lugar, entre elas as notas e o feedback de pessoas.
• A API de leitura sob /v1/api, que a interface e os SDKs usam, os dois. Não existe uma API privada atrás da que você recebe.
• A superfície de execução sob /v1/api/runs, /v1/api/events e /v1/api/steps: definições, execuções, os eventos que respondem a uma espera e o protocolo que um worker fala. Veja Workflows.
• A interface do operador em /, embutida no binário.

Uma porta só é uma decisão de implantação, e não um atalho. Um coletor, um banco de dados e uma interface são três coisas para rodar, três coisas para atualizar e três lugares entre os quais um trace pode se perder.

O que ele deliberadamente não é

Boa parte do valor aqui vem daquilo que o mcpd se recusa a fazer. Cada recusa remove um motivo pelo qual você teria de mudar o seu agente.

• Não é um framework. O mcpd nunca executa o seu modelo, nunca o escolhe e nunca embrulha o cliente do seu provedor. Ele segura uma execução entre as etapas e deixa tudo que está dentro de uma etapa para o seu código. O seu código chama um modelo do mesmo jeito depois de você adotar o mcpd e antes disso.
• Não fica no caminho da requisição. Ele nunca se coloca entre o seu agente e um provedor. Nada que os seus usuários veem depende de o mcpd estar no ar, porque nada que os seus usuários veem passa por ele.
• Não é um serviço. O daemon não chama nada por padrão. Não há telemetria, nem verificação de licença, nem endpoint de fornecedor. O único tráfego de saída que ele vai fazer é o que você configurar: um --forward-endpoint, o webhook de um monitor ou um modelo juiz. Não defina nenhum deles e os seus prompts nunca saem da máquina em que você o executou.
• Não é uma dependência obrigatória. Se você apagar o mcpd da sua infraestrutura, a única coisa que para é o registro.

Os seis sinais

O mcpd guarda seis tipos de coisa, e guarda os seis juntos. Os spans são o que rodou. Os logs são as linhas que uma execução emitiu. As métricas são números ao longo do tempo. As notas são o julgamento de uma máquina sobre uma execução. O feedback é o de uma pessoa. Uma nota de aspecto é uma frase que um modelo escreveu sobre uma execução já terminada.

Mantê-los em um único armazenamento é a razão de tudo. Cada sinal carrega o id de trace e o id de span a que pertence, então a pergunta “o que o modelo disse de verdade na execução de que este cliente reclamou, e quanto ela custou” é uma consulta só, em vez de quatro ferramentas e um horário que você tem de casar no olho.

As notas e o feedback ficam separados de propósito. O 0,8 de um avaliador e o polegar para baixo de uma pessoa medem coisas diferentes, e tirar a média dos dois produz um número que não quer dizer nada.

Por que um daemon e não um framework

A observabilidade de framework é boa, e ela chega presa ao framework. Para ser visto, espera-se que um agente tenha sido construído com ele, em geral em uma única linguagem. Essa é uma troca justa para um projeto novo e uma troca impossível para um agente que já existe e já funciona. Os workflows de framework são a mesma troca: duráveis, desde que cada etapa esteja escrita na linguagem do framework e rode dentro do processo dele.

Um daemon inverte as duas coisas. O grafo de um workflow é dado que o daemon guarda; os corpos das etapas dele são código que o seu processo guarda, reivindicado um lease por vez através de um protocolo HTTP que qualquer linguagem consegue falar. O daemon nunca vê um modelo, um prompt ou uma credencial. Veja Workflows e Workers.

Um daemon inverte a troca. O mcpd fala OTLP, que é um protocolo e não uma dependência, então ele registra agentes escritos em qualquer linguagem, com qualquer framework, inclusive os que foram escritos antes de o mcpd existir. Se o seu agente já exporta OpenTelemetry, apontar OTEL_EXPORTER_OTLP_ENDPOINT para o mcpd é a integração inteira.

Os SDKs existem porque o OTLP não tem vocabulário para um prompt, uma resposta do modelo, uma contagem de tokens ou uma nota, e são esses os campos pelos quais você veio. Usar um deles é uma escolha, não uma condição. Os seis se comportam de forma idêntica: registrar um span acrescenta a uma fila limitada e retorna, o trabalho de rede acontece em um worker de segundo plano, e nada no caminho da instrumentação lança uma exceção. Uma observabilidade capaz de derrubar o sistema que observa é pior do que nenhuma.

Um binário, duas implantações

O contêiner que você roda em um notebook é o contêiner que roda como um Deployment no cluster de alguém. Retenção, ocultação, amostragem e chaves de API são opções nesse mesmo binário, não um build diferente e não um nível de licença. Não existe recurso que só exista em uma versão que você não pode ter.

Os padrões são feitos para o notebook, o que quer dizer que a ingestão e as leituras ficam abertas quando nenhuma chave está configurada. O mcpd avisa de forma bem visível na inicialização quando está escutando em um endereço que não é de loopback nesse estado. Ele inicia mesmo assim, porque recusar quebraria o caminho de cinco minutos para a pessoa a quem ele se destina, mas o silêncio seria irresponsável.

Para onde ir agora

• Rodando agora: Início rápido coloca na tela um trace do seu próprio agente, ou Instalação cobre todos os caminhos de entrada.
• Aprendendo o vocabulário: Conceitos define trace, span, tipo e correlação, que o resto da documentação pressupõe.
• Segurando uma execução entre as etapas: Workflows, depois Workers e Execuções.
• Já tem OpenTelemetry: o caminho OTLP por inteiro, inclusive o que o mcpd deduz dos atributos padrão.
• Rodando para outras pessoas: Docker e Kubernetes, depois Ocultação e retenção.

O mcpd é licenciado sob a Apache-2.0. O protocolo de entrada, o formato de saída e a licença em volta são todos abertos, então sair custa tão pouco quanto chegar.