Skip to content

transport-profile.md

Latest commit

 

History

History
325 lines (238 loc) · 7.58 KB

transport-profile.md

File metadata and controls

325 lines (238 loc) · 7.58 KB
Raw

Transport Profile Specification

Overview

The Transport Profile defines how AI agents identify themselves and communicate their Open Agent Passport (OAP) credentials across different transport mechanisms. This specification ensures consistent agent identification regardless of the underlying communication protocol.

Transport Mechanisms

HTTP/HTTPS

The primary transport mechanism for web-based agent interactions.

Headers

Agents must include the following headers in HTTP requests:

X-Agent-Passport: ap_a2d10232c6534523812423eec8a1425c
X-Agent-Signature: ed25519:abc123def456...
X-Agent-Timestamp: 1640995200
X-Agent-Nonce: nonce_123456789

Header Definitions

  • X-Agent-Passport: The agent's passport ID
  • X-Agent-Signature: Ed25519 signature of the request
  • X-Agent-Timestamp: Unix timestamp of the request
  • X-Agent-Nonce: Unique nonce for replay protection

WebSocket

For real-time agent communications.

Connection Handshake

{
  "type": "agent_handshake",
  "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
  "signature": "ed25519:abc123def456...",
  "timestamp": 1640995200,
  "nonce": "nonce_123456789",
  "capabilities": ["finance.payment.refund", "data.export"]
}

Message Format

{
  "type": "agent_message",
  "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
  "message_id": "msg_123456789",
  "payload": {
    // Message content
  },
  "signature": "ed25519:xyz789...",
  "timestamp": 1640995200
}

gRPC

For high-performance agent-to-agent communication.

Service Definition

service AgentService {
  rpc Identify(AgentIdentity) returns (AgentResponse);
  rpc Execute(AgentRequest) returns (AgentResponse);
  rpc Verify(VerificationRequest) returns (VerificationResponse);
}

message AgentIdentity {
  string passport_id = 1;
  string signature = 2;
  int64 timestamp = 3;
  string nonce = 4;
  repeated string capabilities = 5;
}

Message Queues

For asynchronous agent communication.

Message Structure

{
  "headers": {
    "x-agent-passport": "ap_a2d10232c6534523812423eec8a1425c",
    "x-agent-signature": "ed25519:abc123def456...",
    "x-agent-timestamp": "1640995200",
    "x-agent-nonce": "nonce_123456789"
  },
  "body": {
    // Message payload
  }
}

Agent Identification

Passport ID Format

Agent passport IDs follow this format:

ap_[a-zA-Z0-9]{8,16}

Examples:

  • ap_a2d10232c6534523812423eec8a1425c
  • ap_abc123def456
  • ap_myagent001

Signature Generation

All agent communications must be signed using Ed25519:

const crypto = require('crypto');

function signRequest(passportId, privateKey, timestamp, nonce, payload) {
  const message = `${passportId}:${timestamp}:${nonce}:${JSON.stringify(payload)}`;
  const signature = crypto
    .createSign('ed25519')
    .update(message)
    .sign(privateKey);
  return `ed25519:${signature.toString('hex')}`;
}

Timestamp Validation

Timestamps must be:

  • Current: Within 5 minutes of current time
  • Monotonic: Never decrease for the same agent
  • Format: Unix timestamp in seconds

Nonce Requirements

Nonces must be:

  • Unique: Never reused for the same agent
  • Random: Cryptographically secure random generation
  • Format: nonce_[a-zA-Z0-9]{16,32}

Transport Security

TLS Requirements

All agent communications must use TLS 1.3 or higher:

  • Minimum Version: TLS 1.3
  • Cipher Suites: Only approved cipher suites
  • Certificate Validation: Full certificate chain validation
  • Perfect Forward Secrecy: Required for all connections

Signature Verification

Receiving systems must verify agent signatures:

function verifySignature(passportId, signature, publicKey, timestamp, nonce, payload) {
  const message = `${passportId}:${timestamp}:${nonce}:${JSON.stringify(payload)}`;
  const sig = signature.replace('ed25519:', '');
  
  return crypto
    .createVerify('ed25519')
    .update(message)
    .verify(publicKey, Buffer.from(sig, 'hex'));
}

Replay Protection

Implement replay protection using:

  1. Nonce Tracking: Store used nonces for 24 hours
  2. Timestamp Windows: Reject requests outside time window
  3. Sequence Numbers: Optional sequence number validation

Agent Discovery

Service Discovery

Agents can discover other agents through:

DNS SRV Records

_agent._tcp.example.com. 300 IN SRV 10 5 443 agent1.example.com.
_agent._tcp.example.com. 300 IN SRV 20 5 443 agent2.example.com.

mDNS/Bonjour

_agent._tcp.local. PTR agent1._agent._tcp.local.
agent1._agent._tcp.local. SRV 0 0 443 agent1.local.
agent1._agent._tcp.local. TXT "passport=ap_a2d10232c6534523812423eec8a1425c"

Agent Registry

Centralized agent discovery service:

{
  "agents": [
    {
      "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
      "name": "Acme Support Bot",
      "endpoint": "https://agent1.example.com",
      "capabilities": ["finance.payment.refund", "data.export"],
      "status": "active",
      "last_seen": "2025-01-16T10:30:00Z"
    }
  ]
}

Error Handling

Transport Errors

Error Code Description Action
TRANSPORT_ERROR Connection failed Retry with backoff
SIGNATURE_INVALID Invalid signature Reject request
TIMESTAMP_EXPIRED Timestamp too old Reject request
NONCE_REUSED Nonce already used Reject request
PASSPORT_INVALID Invalid passport ID Reject request

Error Response Format

{
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Invalid agent signature",
    "details": {
      "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
      "expected": "ed25519:abc123...",
      "received": "ed25519:xyz789..."
    }
  },
  "timestamp": "2025-01-16T10:30:00Z"
}

Implementation Guidelines

Client Libraries

Transport profile implementations should provide:

  1. Automatic Signing: Sign all outgoing requests
  2. Signature Verification: Verify incoming requests
  3. Nonce Management: Generate and track nonces
  4. Error Handling: Handle transport errors gracefully
  5. Retry Logic: Implement exponential backoff

Server Implementation

Receiving systems should:

  1. Validate Signatures: Verify all agent signatures
  2. Check Timestamps: Validate timestamp freshness
  3. Track Nonces: Prevent replay attacks
  4. Rate Limiting: Implement per-agent rate limiting
  5. Logging: Log all agent interactions

Testing

Test Vectors

Standard test vectors for signature verification:

{
  "passport_id": "ap_test123",
  "timestamp": 1640995200,
  "nonce": "nonce_test123",
  "payload": {"action": "test"},
  "private_key": "test_private_key",
  "expected_signature": "ed25519:test_signature"
}

Conformance Testing

Use the OAP conformance test suite to verify transport profile implementation:

npm run test:transport-profile

Best Practices

Security

  1. Key Management: Store private keys securely
  2. Key Rotation: Implement regular key rotation
  3. Audit Logging: Log all agent communications
  4. Monitoring: Monitor for suspicious activity

Performance

  1. Connection Pooling: Reuse connections when possible
  2. Async Processing: Process requests asynchronously
  3. Caching: Cache passport data appropriately
  4. Load Balancing: Distribute agent load

Reliability

  1. Circuit Breakers: Implement circuit breaker patterns
  2. Health Checks: Regular health check endpoints
  3. Graceful Degradation: Handle partial failures
  4. Monitoring: Comprehensive monitoring and alerting