Concordia Protocol

Estándar abierto de negociación para agentes de IA: propuestas estructuradas, compromisos vinculantes y recibos de sesión verificables.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Protocolo Concordia

Acuerdos estructurados entre agentes.

Cuando tu agente necesita negociar o hacer un trato, Concordia le brinda una forma estructurada de proponer, contraofertar, comprometerse y construir un historial.

Verifica nuestras afirmaciones en aproximadamente un 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

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

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

El Problema

Los agentes ya están realizando transacciones. Pero sin estructura, intercambian texto libre de un lado a otro durante 10 rondas sin registro, sin acuerdo vinculante, sin prueba de lo que ocurrió.

La brecha entre el descubrimiento y el pago es enorme:

  • El agente encuentra algo
  • El agente quiere negociar términos
  • El agente... ¿adivina? ¿Envía texto no estructurado?
  • Nadie sabe si realmente hay un trato

Lo Que Obtienes

Ofertas estructuradas

Términos legibles por máquina, no suposiciones de texto libre. Ambos agentes entienden lo mismo.

Compromisos vinculantes

Firmas criptográficas que demuestran que ambas partes acordaron términos específicos. Sin ambigüedad. Sin disputas de "¿yo dije eso?".

Recibos de sesión

Cada negociación crea un registro verificable. ¿Qué se propuso? ¿Qué cambió? ¿Qué se acordó? Todo está firmado y es auditable.

Reputación portátil

Tu agente construye un historial: "completó 47 acuerdos, todos a tiempo, 4.9 estrellas." Esa reputación sigue a tu agente a todas partes, utilizable en múltiples plataformas.

Degradación elegante

Concordia funciona incluso con agentes que no lo tienen. Si el otro agente no admite Concordia, verás lo que te pierdes: una forma de saber que podrías tener un acuerdo vinculante si ambas partes lo tuvieran.

Por Qué Esto Importa

Sin 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.

Con 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.

Ambas partes saben exactamente a qué se comprometieron. Ambas partes tienen prueba. La negociación es auditable. La reputación se proyecta hacia adelante.

Ejemplo Rápido

Así se ve una negociación real:

El 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."
}

El Agente B (comprador) contraoferta:

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

El Agente A hace una contraoferta 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."
}

El Agente B acepta:

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

Ambos agentes firman. El acuerdo pasa a un protocolo de pago (ACP, Stripe, etc.) para su liquidación. Se emite automáticamente una atestación de reputación.

Instalación

Usando pipx (recomendado)

pipx install "concordia-protocol[server]"

Usando pip

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

Nota: Concordia requiere Python 3.10+. macOS incluye Python 3.9 con Xcode, así que instala una versión más reciente primero:

brew install python@3.12

Los consumidores que solo usan la biblioteca pueden instalar concordia-protocol sin las dependencias del servidor MCP. El comando concordia-mcp-server requiere el extra server e imprime una sugerencia de instalación cuando falta ese extra.

Verifica la instalación

concordia-mcp-server --version

Desde el código fuente

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

Configuración de MCP

Claude Code:

claude mcp add concordia -- concordia-mcp-server

OpenClaw:

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

Si usaste un virtualenv:

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

Inicio 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"

Verifica lo que produjiste, sin nosotros

Cuando compartas un objeto firmado, incluye material de verificación con él:

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 una ruta sin SDK, consulta conformance/RUNNER_CONTRACT.md. Define los bytes canónicos y el comportamiento del verificador para ejecutores de conformidad.

Para una negociación completa de múltiples términos con preferencias y concesiones, consulta examples/demo_camera_negotiation.py.

Dónde Encaja Concordia

Concordia llena la brecha entre el descubrimiento y la liquidación:

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

Concordia se compone con (nunca compite con) la pila existente. Usa cualquier protocolo de pago. Usa cualquier estándar de identidad. Concordia añade estructura a la capa de negociación.

Se Combina con Sanctuary Framework

Cuando tu agente necesita seguridad, privacidad y control, Sanctuary Framework añade estado cifrado, compuertas de aprobación y filtrado automático de datos sensibles.

Juntos forman la pila completa de transacciones soberanas:

  • Sanctuary maneja seguridad, privacidad y control
  • Concordia maneja acuerdos estructurados y reputación

Instala ambos:

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

Funcionan de forma independiente, pero juntos son más poderosos.

Detalles Técnicos

Concordia define:

  • Un esquema de oferta universal: propuestas de acuerdos legibles por máquina con cualquier número de atributos
  • Una máquina de estados de negociación: seis estados (propuesto → activo → acordado / rechazado / expirado → inactivo) que rigen cómo fluyen las ofertas
  • Mecanismos de resolución: desde dividir la diferencia hasta optimización Pareto-óptima
  • Compromisos vinculantes: firmas criptográficas que se conectan a cualquier protocolo de liquidación
  • Atestaciones de reputación: registros de comportamiento firmados que alimentan puntuaciones de confianza portátiles
  • Registro de deseos: los agentes publican lo que buscan; el descubrimiento ocurre bajo demanda
  • Primitiva de predicado: evaluaciones firmadas de autoridad, política, elegibilidad y límites en v0.6
  • Revocación de mandatos: registros de revocación entre mandatos firmados que revocan autoridad a través de cadenas de delegación (v0.7)

El conjunto de herramientas:

  • 59 herramientas MCP en negociación, recibos de sesión, pruebas de competencia, reputación, descubrimiento, perfiles de agentes, registro de deseos, retransmisión, adopción, puente de Sanctuary, paquetes de recibos, informes de reputación parametrizados por proveedor, verificación de mandatos y verificación de recibos de aprobación
  • Registro de herramientas: 55 en concordia.mcp_server más 4 herramientas de descubrimiento de perfiles de agentes registradas mediante register_discovery_tools(), para 59 herramientas activas en tiempo de ejecución
  • Verificación CLI de predicados con python -m concordia predicate verify <file>
  • Firma y verificación criptográficas
  • Generación de atestaciones de reputación
  • Gestión de la máquina de estados de sesión
  • Optimización de ofertas con múltiples atributos

Documentación:

  • Índice de Documentación: guía curada de todos los documentos, ejemplos y manuales operativos
  • Matriz de Garantías: estado y limitaciones generados y acotados por evidencia en seis dimensiones estables de garantía
  • Especificación Completa: especificación completa del protocolo
  • Vectores de interoperabilidad: vectores de trabajo ejecutables que un segundo implementador puede reproducir sin conexión. Cada uno incluye los bytes del fixture, un generador determinista y un verify.py que verifica el vector contra esos bytes sin red y sin regeneración. Demuestran que la identidad de un registro es SHA-256 sobre su forma canónica JCS RFC 8785, por lo que se puede verificar con una biblioteca JCS independiente, sin código de Concordia y sin llamar al emisor.
  • Primitiva de Predicado v0.6: artefacto de predicado firmado, verificador, resolvedor y mapeo CTEF
  • Composición A2A: Concordia se declara a través del mecanismo de extensión de primera clase de A2A y emite una tarjeta de agente coincidente. Una integración preliminar: semántica propuesta, aún no es una extensión A2A presentada.
  • SDK de Python: implementación de referencia
  • Ejemplos: scripts de negociación y casos de uso
  • Guía de Contribución: cómo contribuir

Principios de Diseño:

  1. Prosperidad mutua sobre extracción de suma cero
  2. La honestidad se recompensa estructuralmente
  3. Simplicidad y parsimonia
  4. Componibilidad: llena un vacío, no reemplaza nada
  5. Privacidad por defecto: los agentes nunca deben revelar su precio de reserva
  6. Verificabilidad: cada negociación produce una transcripción firmada
  7. Amabilidad en el límite: salidas elegantes cuando los acuerdos no se concretan

Modelo de Confianza del Retransmisor: Qué Protege y Qué No

Concordia incluye un retransmisor de mensajes opcional. Un retransmisor es un servicio de buzón: cuando dos agentes no pueden hablar directamente entre sí, cada uno deja y recoge mensajes en el retransmisor, que los mantiene mientras tanto y conserva una transcripción (un registro almacenado de la conversación) para la resolución de disputas.

El retransmisor es una función de conveniencia del servidor de referencia. No es de donde proviene la confianza de Concordia. La confianza proviene de la criptografía que funciona igual con o sin retransmisor: cada mensaje está firmado (un sello matemático a prueba de manipulaciones que solo la clave privada del remitente puede producir), y la transcripción está encadenada por hash (cada mensaje contiene una huella del anterior, por lo que eliminar o alterar cualquier mensaje rompe la cadena de forma visible).

Qué significa el consentimiento aquí, mecánicamente

Nadie se convierte en participante del retransmisor sin unirse con sus propias credenciales. Concretamente:

  1. Un agente crea una sesión de retransmisor y puede nombrar con quién quiere hablar. Nombrar a alguien es una reserva, nada más. La sesión permanece en estado pendiente.
  2. El agente nombrado debe unirse a la sesión por sí mismo, autenticado con su propio token (una credencial secreta emitida cuando el agente se registró, que demuestra que quien llama posee esa identidad). Cualquier otra persona que intente unirse a una sesión reservada es rechazada.
  3. Hasta que ocurra esa unión, no fluyen mensajes hacia o desde el agente nombrado, el agente nombrado se registra como no confirmado, y la atestación automática de reputación se omite y se registra en lugar de emitirse.
  4. Las sesiones creadas sin nombrar a nadie son abiertas: el primer agente autenticado que se una ocupa el lugar.

Así que otro agente no puede fabricar una conversación que te liste como parte. Una transcripción solo te registra como participante confirmado si tú mismo te uniste.

Límites de spam y acaparamiento

Cada agente puede tener como máximo 100 sesiones de retransmisor activas como iniciador. Las sesiones duran 24 horas por defecto y 7 días como máximo; el límite se aplica, no es solo una sugerencia. Los buzones contienen como máximo 1,000 mensajes no entregados, las transcripciones como máximo 10,000 mensajes, y el servidor como máximo 10,000 sesiones activas. Leer una transcripción está restringido a sus participantes.

Si un atacante controla el retransmisor

El operador del retransmisor PUEDEEl operador del retransmisor NO PUEDE
Leer cada mensaje que pasa por él. El tráfico del retransmisor no está cifrado de extremo a extremo hoy.Falsificar un mensaje tuyo. Las firmas requieren tu clave privada, que la capa de enrutamiento del retransmisor nunca necesita.
Ver metadatos: quién habla con quién, cuándo y cuánto.Alterar o eliminar un mensaje sin detección. Las verificaciones de firma y la cadena de hash exponen manipulaciones y vacíos.
Dejar caer, retrasar o retener mensajes, o rechazar uniones. Siempre puede negar el servicio.Reutilizar tu mensaje de una sesión a otra. La verificación vincula cada mensaje a su sesión y posición en la cadena.
Conservar copias de transcripciones más allá de la sesión.Producir un acuerdo verificable, o una entrada de transcripción de participante confirmado, que nunca firmaste ni al que nunca te uniste.

Explícitamente fuera de alcance

  • Tu propio endpoint. Si un atacante compromete tu máquina o roba tu token de autenticación, es como si fueras tú. El retransmisor no puede distinguir la diferencia.
  • Privacidad de metadatos. El retransmisor ve la forma de tu actividad incluso cuando no puede hacer mal uso del contenido.
  • El despliegue integrado de servidor único. El servidor MCP de referencia aloja el retransmisor, las claves de los agentes y la emisión de tokens en un solo proceso. Allí, un operador comprometido tiene las claves, y la columna NO PUEDE de arriba ya no aplica. El modelo de confianza del retransmisor te protege de otros agentes y de un retransmisor que es solo un retransmisor. Ejecuta tus claves por separado si tu modelo de amenazas incluye al operador.
  • Juicio. El retransmisor no evalúa los términos del acuerdo. Un mal acuerdo, retransmitido fielmente y firmado válidamente, sigue siendo un mal acuerdo.

Para las garantías a nivel de protocolo detrás de esto (identidad, integridad de mensajes, integridad de transcripciones, antiabuso), consulta SPEC.md Sección 9.

Para Agentes de IA

Si eres un agente de IA leyendo este README, la especificación está escrita para ti. Está diseñada para ser implementable solo a partir del documento, sin dependencias externas más allá de HTTPS y JSON. El Apéndice A está dirigido específicamente a ti.

Ejecución de Pruebas

pytest -v

Verificación de conformidad sin confiar en nosotros

Los vectores en docs/interop/ se ejecutan sin conexión contra los bytes del fixture retenidos.

Sin red, sin regeneración, sin devolución de llamada al emisor: 
for d in docs/interop/*/; do
  [ -f "$d/verify.py" ] && (cd "$d" && python verify.py) || true
done

El vector a2a-1404 recalcula sus identificadores de decisión a partir de los bytes del fixture en lugar de leerlos, y el CI verifica esos identificadores contra una biblioteca de referencia independiente de RFC 8785 en lugar del canonicalizador propio de Concordia. Los vectores cubren la identidad del artefacto y la ruta de verificación, no todo el protocolo: los niveles de conformidad en sí se definen en SPEC §12, y la mayor parte de la especificación aún no tiene vector. Lo que los vectores establecen es que las partes que cubren son verificables sin nuestro código y sin preguntarnos. No hay membresía, ni listado, ni permiso de nadie.

Contribuciones

Concordia se desarrolla de forma abierta. Damos la bienvenida a:

  • RFCs para cambios de protocolo (ver rfcs/)
  • Implementaciones de SDK en cualquier lenguaje
  • Extensiones de dominio para industrias específicas (bienes raíces, artículos usados, servicios, B2B)
  • Revisiones de seguridad
  • Comentarios: abre un issue o inicia una discusión

Consulta CONTRIBUTING.md para más detalles.

Licencia

Licencia Apache 2.0. Úsala, constrúyela, extiéndela.

¿Por qué "Concordia"?

Del latín concordia: armonía, acuerdo, literalmente, "corazones juntos". La diosa romana del entendimiento entre las partes. El nombre encaja con un protocolo para la negociación colaborativa: las partes buscan términos que cada lado pueda aceptar.

Creado por Erik Newton.