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]