--- license: Apache-2.0 name: fipa-00023-agent-management description: FIPA standard for agent platform management including lifecycle, directory, and communication services category: Research & Academic tags: - fipa - agents - standards - agent-management - interoperability --- # SKILL.md — FIPA Agent Management: Multi-Agent Infrastructure Patterns ```yaml metadata: name: fipa-agent-management version: XC00023H description: > Canonical patterns for naming, registering, lifecycling, and managing autonomous agents in multi-agent systems. Derived from the FIPA Agent Management Specification — the normative standard for interoperable agent infrastructure. activation_triggers: - designing multi-agent orchestration systems - implementing agent discovery or capability routing - building skill registries or service directories - handling agent failures or retry logic in distributed systems - designing agent identity, addressing, or transport layers - modeling agent state or lifecycle transitions - building federated or hierarchical agent platforms ``` ## Decision Points ### Core Architecture Choice ``` IF building single-organization agent platform (< 50 agents): ├─ Use single AMS + single DF ├─ Direct resolution of AIDs to transport addresses └─ Flat capability search across all agents ELSE IF building multi-organization/federated system: ├─ Use federated DF architecture ├─ Each organization runs own AMS/DF pair ├─ DFs register with parent/peer DFs └─ Search propagates with max-depth bounds ``` ### Agent Discovery Strategy ``` IF agent needs specific capability: ├─ Query local DF first with service description ├─ IF no results AND federated topology exists: │ └─ Propagate search to federated DFs (depth ≤ 3) └─ ELSE IF no results in flat topology: └─ Return "capability not available" (don't retry) IF agent joins platform: ├─ Register with AMS first (establish identity + lifecycle state) ├─ THEN register capabilities with DF └─ Registration order matters: existence before capabilities ``` See `references/agent-discovery-without-omniscience.md` for why a single central registry eventually fails under real-world dynamic conditions. ### Failure Recovery Logic ``` IF receive typed FIPA exception: ├─ unsupported/unrecognised → route to different agent type ├─ missing/malformed → fix request parameters, retry once ├─ unauthorised → escalate to platform admin ├─ not-registered → agent reference stale, re-discover via DF ├─ already-registered → idempotent operation, continue └─ internal-error → exponential backoff retry (max 3 attempts) ELSE IF receive non-FIPA error or timeout: ├─ Mark agent as Unknown in AMS ├─ Trigger platform-level health check └─ Do not retry until health restored ``` ### Lifecycle State Transitions ``` IF need to send request to agent: ├─ Query AMS for current lifecycle state ├─ IF state = Active: send immediately ├─ IF state = Waiting: send with acknowledgment protocol ├─ IF state = Suspended: queue or route to alternative └─ IF state = Unknown/Transit: wait for state resolution IF agent reports failure/becomes unresponsive: ├─ AMS transitions agent to Unknown state ├─ DF keeps capability registrations (for recovery) ├─ Platform stops routing new requests to agent └─ Initiate recovery protocol (restart/reregister) ``` See `references/lifecycle-states-as-coordination-contracts.md` for when each unavailability state demands a different orchestrator response. ## Failure Modes ### 🚫 **Endpoint Conflation** **Symptoms**: Direct calls to `http://agent.host:8080`, hard-coded URLs in routing logic, broken references when agents move **Detection Rule**: If you store transport addresses as permanent identifiers, you have this anti-pattern **Fix**: Store AIDs only; resolve transport addresses via AMS at invocation time — see `references/fipa-identity-vs-location-separation.md` for the formal AID model ### 🚫 **Registry Collapse** **Symptoms**: Single table/store tracking both agent existence and capabilities, lifecycle changes break service discovery **Detection Rule**: If updating agent state requires touching capability records, you've collapsed the registries **Fix**: Separate AMS (white pages) from DF (yellow pages); independent update operations — see `references/fipa-two-registry-architecture.md` for the canonical separation argument ### 🚫 **Blind Retry Loops** **Symptoms**: Generic error handling that retries all failures identically, no differentiation between temporary vs permanent failures **Detection Rule**: If your retry logic doesn't branch on failure type, you're in blind retry **Fix**: Parse FIPA exception types; different recovery strategies per exception class — see `references/fipa-exception-taxonomy-as-reasoning-tool.md` for the complete taxonomy ### 🚫 **State-Blind Invocation** **Symptoms**: Sending requests without checking agent lifecycle state, timeouts on suspended agents **Detection Rule**: If you invoke agents without AMS state check, you're state-blind **Fix**: Query lifecycle state before invocation; handle each state appropriately ### 🚫 **Discovery Bottleneck** **Symptoms**: Single central DF handling all capability queries, search latency increases with agent count **Detection Rule**: If all capability searches hit the same registry, you have a bottleneck **Fix**: Implement federated DF architecture with bounded search propagation ## Worked Examples ### Example 1: Federated Discovery Across Organizations **Scenario**: Agent in Organization A needs text-translation capability, which exists in Organization B's platform. **Step-by-step execution**: 1. Agent queries local DF: `QUERY-REF(service-type=translation, input-lang=en, output-lang=es)` 2. Local DF returns empty result set 3. Local DF has federated peer registered → propagate search with max-depth=2 4. Organization B's DF receives federated query, matches against registered translator agent 5. Result propagates back: `AID=translator@orgb.com, service-description=...` 6. Agent A resolves AID via Organization B's AMS → gets transport address 7. Agent A sends translation request with REQUEST performative **Novice mistakes**: Querying Organization B directly, storing B's transport address permanently, not using AID resolution **Expert insights**: Federated search is bounded (prevents query storms), AID resolution happens at invocation time (handles agent migration), performative choice signals intent clearly ### Example 2: Agent Failure and Re-registration **Scenario**: Active translation agent crashes mid-task, client needs to detect failure and recover. **Step-by-step execution**: 1. Client sends REQUEST to translator agent → receives timeout (no response) 2. Client queries AMS for agent lifecycle state → returns "Active" (stale) 3. Platform health monitor detects agent unresponsive → AMS transitions to "Unknown" 4. Client retries request → receives `not-registered` exception from message transport 5. Client re-queries DF for translation capability → finds replacement agent 6. Original agent restarts, re-registers with AMS (Initiated → Active transition) 7. Original agent re-registers capabilities with DF 8. Subsequent capability queries return both translator agents **Novice mistakes**: Infinite retry without state checking, assuming agent death means capability unavailable **Expert insights**: AMS state change is separate from DF re-registration, multiple agents can offer same capability, exception type determines recovery strategy ### Example 3: Multi-Protocol AID Update **Scenario**: Agent platform adds MQTT transport alongside existing HTTP, agent needs to be reachable via both protocols. **Step-by-step execution**: 1. Agent updates AMS registration: `AID=agent@platform.com, addresses=[http://host:8080/agent, mqtt://broker:1883/agent]` 2. AMS validates both transport addresses are reachable 3. Clients continue using same AID for agent reference 4. When client resolves AID → AMS returns both addresses, client chooses transport based on capability 5. HTTP clients continue working unchanged 6. New MQTT clients can connect using same agent identity **Novice mistakes**: Creating separate agent identities per protocol, forcing all clients to update references **Expert insights**: Identity stability across transport changes, AID supports multiple addresses natively, transport choice happens at resolution time ## Quality Gates - [ ] Agent identities are symbolic AIDs, not transport addresses - [ ] AMS (white pages) and DF (yellow pages) are separate registration systems - [ ] All agent-to-agent communication checks lifecycle state before invocation - [ ] Error responses use FIPA exception taxonomy, not generic success/failure flags - [ ] Capability searches support both local and federated discovery modes - [ ] Agent registration follows correct sequence: AMS first, then DF - [ ] Federation topology has explicit max-depth bounds on search propagation - [ ] Lifecycle state transitions respect authority rules (AMS vs agent-initiated) - [ ] Message performatives match communication intent (REQUEST vs INFORM vs QUERY) - [ ] Recovery protocols distinguish between agent failure and capability unavailability ## Bundled Assets - **Diagrams** — [`diagrams/INDEX.md`](diagrams/INDEX.md): lifecycle state machine, discovery/registration sequence, and agent addressing decision tree - **References** — [`references/INDEX.md`](references/INDEX.md): deep-dives on AMS/DF separation, AID identity model, exception taxonomy, federated discovery, capability search, lifecycle contracts, registry authorization, message performatives, and platform interoperability ## Not-For Boundaries **Do NOT use this skill for:** - Individual agent reasoning or decision-making → Use [agent-cognition-patterns] instead - Task decomposition within single agent → Use [task-planning-protocols] instead - Agent learning or adaptation strategies → Use [agent-learning-frameworks] instead - User interface design for agent interactions → Use [human-agent-interaction] instead - Business logic or domain-specific agent behaviors → Use domain-specific skills instead **This skill covers infrastructure-level coordination only**: how agents find each other, communicate, and manage shared platform resources. For everything that happens *inside* an individual agent, delegate to other skills.