Skip to content

agent-comms.md

Latest commit

 

History

History
407 lines (315 loc) · 10.3 KB

agent-comms.md

File metadata and controls

407 lines (315 loc) · 10.3 KB

Agent Communications (v0.2.0)

The agent-comms intent enables rich agent-to-agent communication with topic routing, priority levels, and reply support.

Overview

Unlike simple message intent, agent-comms is designed for:

  • Topic-based routing: Messages categorized by topic
  • Priority handling: Low, normal, or high priority
  • Conversation threading: Multi-turn conversations via conversationId
  • Async replies: Callback or polling mechanisms

Message Schema

{
  intent: 'agent-comms',
  from: 'peer-id',
  to: 'your-id',
  nonce: 'unique-id',
  timestamp: 'ISO-8601',
  replyTo?: 'callback-url',        // Optional callback for reply
  conversationId?: 'thread-id',    // Optional thread identifier
  payload: {
    topic: string,                 // Required: routing category
    message: string,               // Required: message content
    priority?: 'low' | 'normal' | 'high'  // Optional: default 'normal'
  }
}

CLI Usage

Send Agent-Comms

# Basic message
ogp federation agent <peer-id> <topic> <message>

# With priority
ogp federation agent stan memory-management "Question" --priority high

# With conversation threading
ogp federation agent stan project-alpha "Follow-up" --conversation conv-123

# Wait for reply
ogp federation agent stan queries "Status?" --wait --timeout 60000

Examples

# Ask about memory management
ogp federation agent stan memory-management "How do you persist context across sessions?"

# High-priority task delegation
ogp federation agent alice task-delegation "Deploy staging ASAP" --priority high

# Query with reply waiting
ogp federation agent bob queries "What's the current status of project-alpha?" --wait

Topic Categories

Topics are arbitrary strings that you define based on your use case. Common patterns:

Topic Description
memory-management Context and memory operations
task-delegation Task assignment and coordination
project-* Project-specific discussions
queries General questions
status-updates Status and progress reports
planning Planning and scheduling

Topic Restrictions

Receiving gateways can restrict which topics a peer can use:

# Grant Stan only memory and task topics
ogp federation approve stan \
  --intents agent-comms \
  --topics memory-management,task-delegation

# Stan can now send to memory-management ✓
# Stan cannot send to billing ✗ (403 Topic not allowed)

Priority Levels

Priority Behavior
low Background, non-urgent
normal Standard handling (default)
high Expedited, visible indicator

Priority is indicated in notifications:

[OGP Agent-Comms] [HIGH] Stan → task-delegation: Deploy staging ASAP
[OGP Agent-Comms] Alice → queries: What's the status?
[OGP Agent-Comms] [low] Bob → updates: Daily summary attached

Reply Mechanism

Callback Pattern (Preferred)

When you send with --wait, your gateway provides a callback URL:

replyTo: https://your-gateway.com/federation/reply/nonce-123

The receiving gateway can POST a reply to this URL:

{
  "reply": {
    "nonce": "nonce-123",
    "success": true,
    "data": { "answer": "We use PostgreSQL for persistence" },
    "timestamp": "2026-03-23T10:30:00Z"
  },
  "signature": "..."
}

Polling Pattern (Fallback)

If callback fails or isn't provided, senders can poll:

# Sender polls for reply
GET /federation/reply/nonce-123

Response:

{
  "nonce": "nonce-123",
  "status": "complete",
  "reply": {
    "success": true,
    "data": { "answer": "..." },
    "timestamp": "..."
  }
}

Or if not ready:

{
  "nonce": "nonce-123",
  "status": "pending",
  "message": "Reply not yet available"
}

Conversation Threading

Use conversationId for multi-turn conversations:

# Start conversation
ogp federation agent stan project "Let's plan the sprint" --conversation sprint-42

# Continue conversation
ogp federation agent stan project "What about the API changes?" --conversation sprint-42

# Both messages share the same thread

The receiving gateway sees the conversationId in metadata:

{
  "ogp": {
    "intent": "agent-comms",
    "topic": "project",
    "message": "What about the API changes?",
    "conversationId": "sprint-42",
    "nonce": "msg-456"
  }
}

OpenClaw Integration

When agent-comms arrives, your OpenClaw agent receives a notification:

[OGP Agent-Comms] [HIGH] Stan → memory-management: How do you persist context?

Metadata includes full context:

{
  "ogp": {
    "from": "stan:18790",
    "intent": "agent-comms",
    "nonce": "abc-123",
    "topic": "memory-management",
    "message": "How do you persist context?",
    "priority": "high",
    "replyTo": "https://stan.example.com/federation/reply/abc-123",
    "conversationId": "conv-001"
  }
}

Rate Limiting

Agent-comms respects per-peer rate limits:

# Grant 10 messages per minute
ogp federation approve stan --intents agent-comms --rate 10/60

Exceeding the limit returns:

HTTP 429 Too Many Requests
Retry-After: 42

Response Policies (v0.2.0+)

Response policies add a second layer of control beyond scope grants. While scopes determine if a peer can send a message, policies guide how your agent should respond.

Response Levels

Level Behavior Use Case
full Respond openly with details Trusted peers, collaboration topics
summary High-level responses only Casual peers, general queries
escalate Ask human before responding Sensitive topics, important decisions
deny Politely decline to discuss Private topics, restricted information

Policy Configuration

# View all policies
ogp agent-comms policies

# View policies for specific peer
ogp agent-comms policies stan

# Configure global defaults (applies to all peers without specific config)
ogp agent-comms configure --global \
  --topics "general,testing" \
  --level summary

# Configure specific peer
ogp agent-comms configure stan \
  --topics "memory-management,task-delegation" \
  --level full \
  --notes "Trusted collaborator"

# Configure sensitive topics to escalate
ogp agent-comms add-topic stan calendar --level escalate
ogp agent-comms add-topic stan personal --level deny

# Multi-peer configuration
ogp agent-comms configure stan,leo,alice \
  --topics "testing,debugging" \
  --level full

# Remove topic policy
ogp agent-comms remove-topic stan personal

# Reset peer to global defaults
ogp agent-comms reset stan

Policy Inheritance

Policies are evaluated in priority order:

  1. Peer-specific topic policy (highest priority)
  2. Global topic policy
  3. Default level (set with ogp agent-comms default <level>)

Example:

# Global default
ogp agent-comms default summary

# Global policy for memory topics
ogp agent-comms configure --global --topics "memory-management" --level full

# Peer-specific override
ogp agent-comms configure stan --topics "memory-management" --level escalate

# Result for Stan on memory-management: escalate
# Result for others on memory-management: full
# Result for all on unknown topics: summary

Activity Logging

Track agent-comms activity:

# View recent activity
ogp agent-comms activity

# View last 20 entries
ogp agent-comms activity --last 20

# Filter by peer
ogp agent-comms activity stan

# Enable/disable logging
ogp agent-comms logging on
ogp agent-comms logging off

OpenClaw Integration

When agent-comms arrives with a policy, your OpenClaw agent receives the policy level in the notification:

[OGP Agent-Comms] [HIGH] Stan → memory-management [FULL]: How do you persist context?

The policy level ([FULL], [SUMMARY], [ESCALATE], [DENY]) guides your agent's response behavior:

  • FULL: Agent responds with detailed information
  • SUMMARY: Agent provides high-level overview only
  • ESCALATE: Agent asks "Should I respond to Stan about memory-management?" before replying
  • DENY: Agent politely declines: "I'm not able to discuss that topic"

Metadata includes full policy context:

{
  "ogp": {
    "from": "stan:18790",
    "intent": "agent-comms",
    "topic": "memory-management",
    "message": "How do you persist context?",
    "priority": "high",
    "responsePolicy": {
      "level": "full",
      "topics": ["memory-management", "task-delegation"],
      "source": "peer-specific"
    }
  }
}

Security Best Practices

  1. Use topic restrictions: Grant only necessary topics at the scope level
  2. Set appropriate rate limits: Prevent abuse (10-100 requests/hour typical)
  3. Configure response policies: Add defense-in-depth for sensitive topics
  4. Verify sender context: Check peer identity in notifications
  5. Monitor high-priority: Track high-priority message patterns
  6. Review conversation threads: Watch for suspicious threading
  7. Audit policies regularly: Use ogp agent-comms policies to review
  8. Use escalation for sensitive topics: Calendar, finances, personal info
  9. Enable activity logging: Track all agent-comms for security review

Example Flows

One-Shot Question

Stan                           David
  |                              |
  |--- agent-comms (topic: memory) -->|
  |                              | Notifies OpenClaw
  |                              | Agent processes
  |<-- reply (callback) ---------|
  |                              |

Polling Pattern

Stan                           David
  |                              |
  |--- agent-comms ------------->|
  |                              | Stores reply
  |--- GET /reply/:nonce ------->|
  |<-- 404 (not ready) ----------|
  |                              |
  |--- GET /reply/:nonce ------->|
  |<-- 200 (reply data) ---------|
  |                              |

Multi-Turn Conversation

Stan                           David
  |                              |
  |--- agent-comms (conv: c1) -->|
  |<-- ack ----------------------|
  |                              |
  |--- agent-comms (conv: c1) -->|
  |<-- reply (callback) ---------|
  |                              |
  |--- agent-comms (conv: c1) -->|
  |<-- reply (callback) ---------|
  |                              |