Fipa 00037 Communicative Act Library

SKILL.md: FIPA Communicative Act Library

name: fipa-communicative-acts
version: 1.0.0
description: >
  Formal semantics and design patterns for multi-agent communication,
  grounded in the FIPA Communicative Act Library specification. Applies
  to agent coordination, protocol design, message routing, and failure handling.
activation_triggers:
  - designing communication protocols between AI agents
  - building multi-agent systems or agent orchestration layers
  - debugging coordination failures between agents
  - designing fallback or error-signaling behavior for agents
  - reasoning about what agents should "say" to each other and why
  - questions about autonomy, commitment, and compliance in agent networks
  - event-driven or subscription-based agent coordination
  - federated or multi-hop agent routing problems

When to Use This Skill

Load this skill when the problem involves agents coordinating with other agents — not just calling tools or APIs, but situations where you need to decide what kind of message to send, design protocols, or handle autonomous agent coordination failures.

DECISION POINTS

Primary Act Selection Decision Tree

What is the sender's knowledge state about the content?
├── I KNOW P is true + want receiver to know it
│   ├── Receiver doesn't know P → inform(P)
│   └── Unsure if receiver knows P → inform-if(P)
├── I DON'T KNOW if P is true + need to find out
│   ├── Want yes/no answer → query-if(P)
│   └── Want specific referent → query-ref(description)
├── I WANT an action performed + receiver is autonomous
│   ├── Direct request → request(action)
│   ├── Need agreement first → propose(action) 
│   └── Conditional execution → request-when(condition, action)
└── RESPONDING to incoming message
    ├── Cannot process → not-understood(original-message)
    ├── Won't comply → refuse(requested-action, reason)
    ├── Tried but failed → failure(attempted-action, reason)
    ├── Agreeing to proposal → accept-proposal(proposal)
    └── Declining proposal → reject-proposal(proposal, reason)

Federation Routing Decision Tree

Is the target agent directly reachable?
├── YES → Send communicative act directly
└── NO → Choose routing strategy:
    ├── Know specific intermediary → proxy(target-agent, message)
    ├── Broadcast to group → propagate(filter-criteria, message)
    └── Store for later → Use subscription/request-whenever pattern

Does this need guaranteed delivery?
├── YES → Require explicit confirm or inform-done responses
└── NO → Send and continue (fire-and-forget acceptable)

Error Handling Strategy Decision Tree

Received unexpected response or timeout?
├── got not-understood → Rephrase with simpler terms or different act
├── got refuse → 
│   ├── Capability issue → Find different agent or modify request
│   └── Context issue → Wait for better conditions or negotiate
├── got failure → Retry with same agent or escalate to different approach
├── got nothing (timeout) →
│   ├── < 30s → Retry once
│   ├── 30s-2min → Send cancel, try different agent
│   └── > 2min → Declare coordination failure, escalate
└── got malformed response → Send not-understood, request clarification

FAILURE MODES

1. "Command Confusion" Anti-Pattern

Symptom: Agent sends request(action) and assumes action will happen without confirmation Detection Rule: If you see coordination logic that doesn't handle refuse or failure responses, this is command confusion Fix: Always design request-response pairs: request(action) → expect (inform-done | refuse | failure)

2. "Silent Drop" Anti-Pattern

Symptom: Agent receives message it cannot process and ignores it silently Detection Rule: If error logs show "unknown message type" without sending not-understood response, this is silent drop Fix: Emit not-understood(original-message) for any unparseable communicative act before continuing

3. "Ontology Overconfidence" Anti-Pattern

Symptom: Agent sends inform(P) when actually uncertain about P's truth value Detection Rule: If you see inform being sent with confidence < 0.8 or from unverified sources, this is ontology overconfidence
Fix: Use inform-if(P) to acknowledge uncertainty, or query-if to gather more information first

4. "Protocol Explosion" Anti-Pattern

Symptom: Creating specialized acts like urgent-notify or status-update instead of composing from primitives Detection Rule: If you see custom message types that aren't grounded in B/U/I mental state changes, this is protocol explosion Fix: Decompose into primitives - urgent-notify(P) becomes inform(P) + priority-flag, status-update becomes inform(current-status)

5. "Timeout Guessing" Anti-Pattern

Symptom: Using arbitrary timeout values (like 5 seconds) without considering act semantics Detection Rule: If timeout logic doesn't vary by communicative act complexity, this is timeout guessing Fix: Scale timeouts by act type - query-ref: 10-30s, request(complex-action): 1-5min, inform: 5-10s

WORKED EXAMPLES

Example 1: Federated Information Gathering

Scenario: Agent A needs to find "latest weather data for San Francisco" but doesn't know which agent has it.

Novice approach: Broadcast query-ref("weather data for San Francisco") to all known agents Expert reasoning:

1. Check ability vs. context relevance - do I have authority to query everyone?
2. Use propagate pattern with filter: propagate(has-capability("weather-data"), query-ref("SF weather"))
3. Handle responses: collect all inform-ref responses, handle not-understood by refining query
4. Timeout after 30s, send cancel to any still-processing agents

Key expert insight: Propagate with filtering scales better than broadcast, and explicit cancellation prevents resource waste.

Example 2: Refusal Handling in Task Delegation

Scenario: Agent A requests Agent B to process_document(large_file.pdf), Agent B responds with refuse(process_document, "file too large")

Novice approach: Retry with same request or give up Expert reasoning:

1. Parse refusal reason - "file too large" indicates capability boundary, not context issue
2. Decision tree: capability issue → find different agent OR modify request
3. Try request(process_document_chunks(split(large_file.pdf, 10MB)))
4. If that also fails, escalate to agent with higher processing limits

Key expert insight: refuse contains structured information about WHY coordination failed, enabling systematic recovery strategies.

Example 3: Timeout Recovery with Mental State Tracking

Scenario: Agent A sends request(calculate_route(complex_params)) to Agent B, no response after 90 seconds

Novice approach: Assume failure, try different agent Expert reasoning:

1. Check timeout threshold - route calculation should complete in 30-60s, so 90s indicates problem
2. Send cancel(calculate_route) to Agent B to clean up resources
3. Update mental model: B might be overloaded or stuck
4. Try Agent C with request(calculate_route(complex_params)), but add timeout metadata
5. If Agent C also delays, simplify params: request(calculate_route(simplified_params))

Key expert insight: Explicit cancellation preserves agent resource management, and timeout patterns inform request modification strategies.

QUALITY GATES

Protocol validation checklist - mark complete when all conditions are verifiable:

• Every request has defined response paths for inform-done, refuse, and failure
• All agents can emit not-understood for unparseable messages
• Mental state preconditions are satisfied before sending each act (sender believes what they claim to believe)
• Timeout thresholds are set based on act complexity: inform 5-10s, query 10-30s, request 30s-5min
• Routing strategy chosen: direct, proxy, or propagate with appropriate filtering criteria
• Error escalation paths defined for each failure mode (refuse → find different agent, failure → retry logic)
• Federation endpoints can handle cancel messages for long-running operations
• Protocol uses composition of primitives rather than custom act types
• Belief/uncertainty/intention states remain consistent across message sequences
• Context-relevance vs. ability preconditions distinguished in refusal handling

NOT-FOR BOUNDARIES

This skill should NOT be used for:

• Single-agent tool calling: Use function/API calling patterns instead
• Deterministic service integration: For REST APIs, database queries, or guaranteed-response services, use standard integration patterns
• Human-agent conversation: For natural language dialog, use conversational AI frameworks instead of formal communicative acts
• Real-time streaming: For high-frequency data streams, use event streaming protocols; FIPA acts are for coordination, not data transfer
• Internal agent reasoning: For agent's private mental state updates, use internal reasoning frameworks

Delegate to other skills:

• For API integration: use [api-integration-patterns]
• For conversation design: use [dialog-management]
• For streaming data: use [event-driven-architecture]
• For internal reasoning: use [cognitive-architecture]