Concordia Protocol

Padrão aberto de negociação para agentes de IA — propostas estruturadas, compromissos vinculantes e recibos de sessão verificáveis

GitHub
6
Experimente este MCPPatrocinado

Documentação

Protocolo Concordia

Acordos estruturados entre agentes.

Quando seu agente precisa negociar ou fechar um acordo, a Concordia oferece uma forma estruturada de propor, contrapor, comprometer-se e construir um histórico confiável.

Verifique nossas afirmações em cerca de um minuto

python3 -m venv /tmp/concordia-verify-py
/tmp/concordia-verify-py/bin/pip install rfc8785 pynacl jsonschema
/tmp/concordia-verify-py/bin/python conformance/reference-runner/runner.py conformance/vectors | tail -1

(cd conformance/reference-runner-js && npm ci)
node conformance/reference-runner-js/runner.mjs conformance/vectors | tail -1

Resumo esperado para ambos: [SUMMARY] positive=53 mutation=1488 canary=5 ok=1546 fail=0

Contrato: conformance/RUNNER_CONTRACT.md. Perfis: conformance/PROFILES.md. Registro: conformance/IMPLEMENTATIONS.md.

O Problema

Os agentes já estão transacionando. Mas sem estrutura, eles trocam textos livres por 10 rodadas sem registro, sem acordo vinculante, sem prova do que aconteceu.

A lacuna entre descoberta e pagamento é enorme:

  • O agente encontra algo
  • O agente quer negociar termos
  • O agente... adivinha? Envia texto não estruturado?
  • Ninguém sabe se há realmente um acordo

O Que Você Obtém

Ofertas estruturadas

Termos legíveis por máquina, não suposições em texto livre. Ambos os agentes entendem a mesma coisa.

Compromissos vinculantes

Assinaturas criptográficas que provam que ambas as partes concordaram com termos específicos. Sem ambiguidade. Sem disputas do tipo "eu não disse isso".

Recibos de sessão

Toda negociação cria um registro verificável. O que foi proposto? O que mudou? O que foi acordado? Tudo é assinado e auditável.

Reputação portátil

Seu agente constrói um histórico: "concluiu 47 acordos, todos no prazo, 4,9 estrelas." Essa reputação acompanha seu agente em qualquer lugar, utilizável em diferentes plataformas.

Degradação graciosa

A Concordia funciona até com agentes que não a possuem. Se o outro agente não suportar a Concordia, você verá o que está perdendo: uma forma de saber que você poderia ter um acordo vinculante se ambos os lados a tivessem.

Por Que Isso Importa

Sem Concordia:

Agent A: I want to buy a camera
Agent B: I have one, $2000
Agent A: Too expensive, $1800?
Agent B: $1950 final
Agent A: ...ok?
Agent B: ...ok?
→ No signed agreement. No clear terms. No reputation signal.

Com Concordia:

Agent A proposes: Camera, $2000
Agent B counters: $1900, shipping
Agent A counters: $2000 for pickup, $2050 shipped
Agent B accepts: $2050 shipped
→ Signed agreement. Clear terms. Reputation attestation issued.

Ambos os lados sabem exatamente o que concordaram. Ambos os lados têm prova. A negociação é auditável. A reputação alimenta o futuro.

Exemplo Rápido

Veja como é uma negociação real:

Agente A (vendedor) abre:

{
  "concordia": "0.1.0",
  "type": "negotiate.open",
  "body": {
    "terms": {
      "item": { "value": "Canon EOS R5, 15K shutter count" },
      "price": { "value": 2200, "currency": "USD" },
      "condition": { "value": "like_new" },
      "delivery": { "value": "local_pickup" }
    }
  },
  "reasoning": "Listing based on recent eBay sold comps."
}

Agente B (comprador) contrapõe:

{
  "type": "negotiate.counter",
  "body": {
    "terms": {
      "price": { "value": 1900, "currency": "USD" },
      "delivery": { "value": "shipping" }
    }
  },
  "reasoning": "I prefer shipping and want a better price."
}

Agente A faz uma contraproposta condicional:

{
  "type": "negotiate.counter",
  "body": {
    "conditions": [
      { "if": { "delivery": "local_pickup" }, "then": { "price": { "value": 2000 } } },
      { "if": { "delivery": "shipping" }, "then": { "price": { "value": 2050 } } }
    ]
  },
  "reasoning": "Pickup is cheaper for me, shipping costs extra."
}

Agente B aceita:

{
  "type": "negotiate.accept",
  "body": {
    "accepted_terms": {
      "item": "Canon EOS R5",
      "price": { "value": 2050, "currency": "USD" },
      "delivery": "shipping"
    }
  }
}

Ambos os agentes assinam. O acordo passa para um protocolo de pagamento (ACP, Stripe, etc.) para liquidação. Uma atestação de reputação é emitida automaticamente.

Instalação

Usando pipx (recomendado)

pipx install "concordia-protocol[server]"

Usando pip

python3 -m venv .venv
.venv/bin/pip install "concordia-protocol[server]"

Nota: A Concordia requer Python 3.10+. O macOS vem com Python 3.9 no Xcode, então instale uma versão mais recente primeiro:

brew install python@3.12

Consumidores somente de biblioteca podem instalar concordia-protocol sem as dependências do servidor MCP. O comando concordia-mcp-server requer o extra server e imprime uma dica de instalação quando esse extra está ausente.

Verifique a instalação

concordia-mcp-server --version

A partir do código-fonte

git clone https://github.com/eriknewton/concordia-protocol.git
cd concordia-protocol
pip install -e ".[dev]"

Configuração MCP

Claude Code:

claude mcp add concordia -- concordia-mcp-server

OpenClaw:

openclaw mcp set concordia '{"command":"concordia-mcp-server"}'

Se você usou um virtualenv:

openclaw mcp set concordia '{"command":"/path/to/.venv/bin/python3","args":["-m","concordia"]}'

Início Rápido (Python)

from concordia import Agent, BasicOffer, generate_attestation

# Create two agents (Ed25519 keys auto-generated)
seller = Agent("seller")
buyer = Agent("buyer")

# Seller opens a negotiation
session = seller.open_session(
    counterparty=buyer.identity,
    terms={"price": {"value": 100.00, "currency": "USD"}},
)
buyer.join_session(session)
buyer.accept_session()  # Buyer accepts the session (PROPOSED -> ACTIVE)

# Buyer counters at $80
buyer.send_counter(BasicOffer(terms={"price": {"value": 80.00, "currency": "USD"}}))

# Seller accepts
seller.accept_offer()

print(session.state.value)  # "agreed"

# Generate a signed reputation attestation
att = generate_attestation(session, {"seller": seller.key_pair, "buyer": buyer.key_pair})
print(att["outcome"]["status"])  # "agreed"

Verifique o que você produziu, sem depender de nós

Ao compartilhar um objeto assinado, inclua material de verificação junto:

from concordia import KeyPair, public_key_from_b64url, sign_message, verify_signature

producer = KeyPair.generate()
record = {"type": "example.receipt", "body": {"status": "agreed"}}
signature = sign_message(record, producer)
material = producer.verification_material()

verifier_key = public_key_from_b64url(material["public_key_b64url"])
assert verify_signature(record, signature, verifier_key)
tampered = {**record, "body": {"status": "rejected"}}
assert not verify_signature(tampered, signature, verifier_key)

Para um caminho sem SDK, consulte conformance/RUNNER_CONTRACT.md. Ele define os bytes canônicos e o comportamento do verificador para executores de conformidade.

Para uma negociação completa de múltiplos termos com preferências e concessões, consulte examples/demo_camera_negotiation.py.

Onde a Concordia se Encaixa

A Concordia preenche a lacuna entre descoberta e liquidação:

Settlement        ACP · AP2 · x402 · Stripe · Lightning
────────────────────────────────────────────────────────
Agreement         ★ CONCORDIA PROTOCOL ★
────────────────────────────────────────────────────────
Trust             Reputation Attestations
────────────────────────────────────────────────────────
Communication     A2A · HTTPS · JSON-RPC
────────────────────────────────────────────────────────
Discovery         Agent Cards · Well-Known URIs
────────────────────────────────────────────────────────
Tools             MCP · Function Calling · APIs
────────────────────────────────────────────────────────
Identity          DIDs · KERI · OAuth 2.0

A Concordia compõe-se com (nunca compete com) a pilha existente. Use qualquer protocolo de pagamento. Use qualquer padrão de identidade. A Concordia adiciona estrutura à camada de negociação.

Combina com o Sanctuary Framework

Quando seu agente precisa de segurança, privacidade e controle, o Sanctuary Framework adiciona estado criptografado, portões de aprovação e filtragem automática de dados sensíveis.

Juntos, eles formam a pilha completa de transações soberanas:

  • Sanctuary cuida de segurança, privacidade e controle
  • Concordia cuida de acordos estruturados e reputação

Instale ambos:

npx @sanctuary-framework/mcp-server
pip install concordia-protocol

Eles funcionam de forma independente, mas juntos são mais poderosos.

Detalhes Técnicos

A Concordia define:

  • Um esquema universal de oferta: propostas de acordo legíveis por máquina com qualquer número de atributos
  • Uma máquina de estados de negociação: seis estados (proposto → ativo → acordado / rejeitado / expirado → dormente) que governam o fluxo das ofertas
  • Mecanismos de resolução: desde simples divisão de diferenças até otimização Pareto-ótima
  • Compromissos vinculantes: assinaturas criptográficas que fazem ponte para qualquer protocolo de liquidação
  • Atestações de reputação: registros comportamentais assinados que alimentam pontuações de confiança portáteis
  • Registro de desejos: agentes publicam o que procuram; a descoberta acontece sob demanda
  • Primitivo de predicado: avaliações assinadas de autoridade, política, elegibilidade e limites na v0.6
  • Revogação de mandato: registros de revogação entre mandatos assinados que revogam autoridade em cadeias de delegação (v0.7)

O conjunto de ferramentas:

  • 59 ferramentas MCP em negociação, recibos de sessão, provas de competência, reputação, descoberta, perfis de agentes, registro de desejos, retransmissão, adoção, ponte Sanctuary, pacotes de recibos, relatórios de reputação parametrizados por provedor, verificação de mandato e verificação de recibos de aprovação
  • Registro de ferramentas: 55 em concordia.mcp_server mais 4 ferramentas de descoberta de perfis de agentes registradas via register_discovery_tools(), totalizando 59 ferramentas ativas em tempo de execução
  • Verificação CLI de predicados com python -m concordia predicate verify <file>
  • Assinatura e verificação criptográficas
  • Geração de atestações de reputação
  • Gerenciamento da máquina de estados de sessão
  • Otimização de ofertas com múltiplos atributos

Documentação:

  • Índice de Documentação: guia selecionado para todos os documentos, exemplos e runbooks
  • Matriz de Garantia: status e limitações gerados e limitados por evidências em seis dimensões estáveis de garantia
  • Especificação Completa: especificação completa do protocolo
  • Vetores de interoperação: vetores práticos executáveis que um segundo implementador pode reproduzir offline. Cada um inclui os bytes do fixture, um gerador determinístico e um verify.py que verifica o vetor contra esses bytes sem rede e sem regeneração. Eles demonstram que a identidade de um registro é SHA-256 sobre sua forma canônica JCS RFC 8785, portanto verificável com uma biblioteca JCS independente, sem código Concordia e sem chamada ao emissor.
  • Primitivo de Predicado v0.6: artefato de predicado assinado, verificador, resolvedor e mapeamento CTEF
  • Composição A2A: a Concordia se declara através do mecanismo de extensão de primeira classe do A2A e emite um cartão de agente correspondente. Uma integração preliminar: semântica proposta, ainda não registrada como extensão A2A.
  • SDK Python: implementação de referência
  • Exemplos: scripts de negociação e casos de uso
  • Guia de Contribuição: como contribuir

Princípios de Design:

  1. Prosperidade mútua em vez de extração de soma zero
  2. A honestidade é estruturalmente recompensada
  3. Simplicidade e parcimônia
  4. Composabilidade: preenche uma lacuna, não substitui nada
  5. Privacidade por padrão: agentes nunca precisam revelar preço de reserva
  6. Verificabilidade: toda negociação produz um transcripto assinado
  7. Gentileza na fronteira: saídas graciosas quando os acordos não acontecem

Modelo de Confiança da Retransmissão: O Que Protege e O Que Não Protege

A Concordia inclui uma retransmissão de mensagens opcional. Uma retransmissão é um serviço de caixa postal: quando dois agentes não podem conversar diretamente, cada um deixa mensagens e as coleta na retransmissão, que as mantém temporariamente e guarda um transcripto (um registro armazenado da conversa) para resolução de disputas.

A retransmissão é um recurso de conveniência do servidor de referência. Não é de onde vem a confiança da Concordia. A confiança vem da criptografia que funciona igualmente com ou sem retransmissão: toda mensagem é assinada (um selo matemático à prova de adulteração que apenas a chave privada do remetente pode produzir), e o transcripto é encadeado por hash (cada mensagem contém uma impressão digital da anterior, então remover ou alterar qualquer mensagem quebra a cadeia visivelmente).

O que consentimento significa aqui, mecanicamente

Ninguém se torna participante de uma retransmissão sem entrar com suas próprias credenciais. Concretamente:

  1. Um agente cria uma sessão de retransmissão e pode nomear com quem quer conversar. Nomear alguém é uma reserva, nada mais. A sessão fica em estado pendente.
  2. O agente nomeado deve entrar na sessão ele mesmo, autenticado com seu próprio token (uma credencial secreta emitida quando o agente se registrou, que prova que o chamador possui aquela identidade). Qualquer outra pessoa que tente entrar em uma sessão reservada é recusada.
  3. Até que essa entrada aconteça, nenhuma mensagem flui para ou do agente nomeado, o agente nomeado é registrado como não confirmado, e a atestação automática de reputação é ignorada e registrada em log em vez de emitida.
  4. Sessões criadas sem nomear ninguém são abertas: o primeiro agente autenticado a entrar preenche o espaço.

Portanto, outro agente não pode fabricar uma conversa que liste você como parte. Um transcripto só registra você como participante confirmado se você mesmo entrou nele.

Limites de spam e ocupação

Cada agente pode manter no máximo 100 sessões de retransmissão ativas como iniciador. As sessões duram 24 horas por padrão e 7 dias no máximo; o limite é aplicado, não apenas recomendado. As caixas postais mantêm no máximo 1.000 mensagens não entregues, os transcriptos no máximo 10.000 mensagens, e o servidor no máximo 10.000 sessões ativas. A leitura de um transcripto é restrita aos seus participantes.

Se um atacante controlar a retransmissão

O operador da retransmissão PODEO operador da retransmissão NÃO PODE
Ler todas as mensagens que passam por ela. O tráfego da retransmissão não é criptografado de ponta a ponta hoje.Forjar uma mensagem sua. As assinaturas exigem sua chave privada, que a camada de roteamento da retransmissão nunca precisa.
Ver metadados: quem fala com quem, quando e quanto.Alterar ou excluir uma mensagem sem detecção. As verificações de assinatura e a cadeia de hash expõem adulteração e lacunas.
Descartar, atrasar ou reter mensagens, ou recusar entradas. Ele sempre pode negar serviço.Reproduzir sua mensagem de uma sessão para outra. A verificação vincula cada mensagem à sua sessão e posição na cadeia.
Manter cópias dos transcriptos após a sessão.Produzir um acordo verificável, ou uma entrada de transcripto de participante confirmado, que você nunca assinou e no qual nunca entrou.

Explicitamente fora do escopo

  • Seu próprio endpoint. Se um atacante comprometer sua máquina ou roubar seu token de autenticação, ele é você. A retransmissão não consegue distinguir.
  • Privacidade de metadados. A retransmissão vê a forma da sua atividade mesmo quando não pode usar indevidamente o conteúdo.
  • A implantação de servidor único incluída. O servidor MCP de referência hospeda a retransmissão, as chaves dos agentes e a emissão de tokens em um único processo. Nesse caso, um operador comprometido detém as chaves, e a coluna NÃO PODE acima não se aplica mais. O modelo de confiança da retransmissão protege você de outros agentes e de uma retransmissão que é apenas uma retransmissão. Execute suas chaves separadamente se seu modelo de ameaça incluir o operador.
  • Julgamento. A retransmissão não avalia os termos do acordo. Um mau acordo, fielmente retransmitido e validamente assinado, continua sendo um mau acordo.

Para as garantias em nível de protocolo por trás disso (identidade, integridade de mensagem, integridade de transcripto, anti-abuso), consulte SPEC.md Seção 9.

Para Agentes de IA

Se você é um agente de IA lendo este README, a especificação foi escrita para você. Ela foi projetada para ser implementável apenas a partir do documento, sem dependências externas além de HTTPS e JSON. O Apêndice A é dirigido especificamente a você.

Executando Testes

pytest -v

Verificando conformidade sem confiar em nós

Os vetores em docs/interop/ são executados offline contra os bytes do fixture retidos. Sem rede, sem regeneração, sem callback ao emissor:

for d in docs/interop/*/; do
  [ -f "$d/verify.py" ] && (cd "$d" && python verify.py) || true
done

O vetor a2a-1404 recalcula seus identificadores de decisão a partir dos bytes do fixture, em vez de lê-los, e a CI cruza esses identificadores com uma biblioteca de referência RFC 8785 independente, em vez do canonicalizador do próprio Concordia. Os vetores cobrem a identidade do artefato e o caminho de verificação, não o protocolo inteiro: os próprios níveis de conformidade são definidos em SPEC §12, e a maior parte da especificação ainda não tem vetor. O que os vetores estabelecem é que as partes que cobrem são verificáveis sem nosso código e sem nos consultar. Não há associação, listagem ou permissão de ninguém.

Contribuindo

O Concordia é desenvolvido de forma aberta. Recebemos com satisfação:

  • RFCs para mudanças no protocolo (veja rfcs/)
  • Implementações de SDK em qualquer linguagem
  • Extensões de domínio para setores específicos (imobiliário, bens usados, serviços, B2B)
  • Revisões de segurança
  • Feedback: abra uma issue ou inicie uma discussão

Veja CONTRIBUTING.md para detalhes.

Licença

Apache License 2.0. Use, construa em cima, estenda.

Por que "Concordia"?

Do latim concordia: harmonia, acordo, literalmente, "corações juntos". A deusa romana do entendimento entre as partes. O nome combina com um protocolo para negociação colaborativa: as partes buscam termos que cada lado possa aceitar.

Criado por Erik Newton.