curiositech/agentspeak-bdi

SKILL.md — AgentSpeak(L) & BDI Agent Architecture

When autonomous entities must perceive, deliberate, and act while managing competing goals and responding to events without abandoning ongoing work.

---

Decision Points

Primary Architecture Selection

IF system needs only event-reaction with no persistent goals
  → Use reactive/rule system (BDI is overkill)
ELIF system needs planning in static environment with no interrupts  
  → Use classical planner
ELIF system needs both reactivity AND goal persistence in dynamic environment
  → Use BDI architecture

Selection Function Invocation Table

| Situation | Use Function | Decision Criteria | |-----------|-------------|-------------------| | New event arrives | SE (Event Selection) | Priority, urgency, resource constraints | | Event needs plan | SO (Option Selection) | Context guards, plan success history, risk tolerance | | Multiple active intentions | SI (Intention Selection) | Deadlines, resource allocation, fairness policy | | Plan failure occurs | SO then SI | Find failure-handling plan, then reschedule intentions |

Plan Failure Recovery Decision Tree

Plan P fails executing action A:
IF failure-handling plan exists for this failure type
  → Post failure event, let SO select recovery plan
  → Continue with modified intention stack
ELIF alternative plans exist for same triggering event
  → Backtrack to event, let SO try next applicable plan  
  → Remove failed plan from consideration
ELIF no alternatives available
  → Propagate failure up intention stack
  → IF parent plan exists → trigger failure event at parent level
  → ELSE drop intention entirely

Belief Update Impact Assessment

New belief B arrives:
IF B contradicts existing beliefs
  → Run belief revision protocol
  → Check all active intentions for context guard violations
  → IF context no longer holds → suspend intention (don't drop)
ELIF B enables new applicable plans
  → Check event queue for dormant events that now have applicable plans
  → Reprioritize using SE
ELIF B satisfies pending goal conditions  
  → Mark achievement, clean up related intentions
  → Post achievement event for plan cleanup

---

Failure Modes

1. Plan Thrashing

Symptoms: Agent rapidly cycles between plans without making progress; same event triggers different plans repeatedly. Detection Rule: If the same event is processed >3 times in N execution cycles with different plan selections each time, you have plan thrashing. Root Cause: SO (option selection) function is non-deterministic or context guards are too weak/overlapping. Fix: Make SO explicitly ordered by priority; strengthen context guards to be mutually exclusive; add plan success/failure history to selection criteria.

2. Stale Belief Paralysis

Symptoms: Agent selects plans based on outdated world model; plans fail immediately due to false assumptions about environment. Detection Rule: If plan failure rate >50% and failures are due to context guard violations at execution time (not planning time), you have stale beliefs. Root Cause: Belief update frequency is too low relative to environment change rate; belief revision is not propagating to intention context checks. Fix: Increase perception frequency; add belief staleness timestamps; suspend intentions when their context guards become invalid.

3. Infinite Intention Loops

Symptoms: Agent creates intentions that post events that create more intentions for the same goal; intention stack grows without bound. Detection Rule: If intention stack depth increases monotonically over time without corresponding goal achievements, you have intention loops. Root Cause: Plans create subgoals that eventually lead back to the original goal without termination conditions. Fix: Add achievement detection in context guards; implement intention subsumption (merge duplicate intentions); add maximum recursion depth limits.

4. Policy-in-Plans Anti-Pattern

Symptoms: Same events trigger different behaviors based on conditionals inside plan bodies; agent policy is scattered and hard to change. Detection Rule: If plan bodies contain priority/urgency conditionals (if high_priority then X else Y), policy is in the wrong place. Root Cause: Agent rationality is encoded in plan logic instead of selection functions. Fix: Move all priority/policy logic to SE/SO/SI functions; make plans policy-neutral and context-sensitive only.

5. Single-Intention Bottleneck

Symptoms: Agent cannot handle interrupts; urgent events wait while agent completes long-running tasks; no concurrency. Detection Rule: If agent has at most one active intention at any time, you have single-intention bottleneck. Root Cause: SI (intention scheduling) function is not implementing true concurrency; treating intentions as exclusive rather than concurrent. Fix: Allow multiple active intentions; implement preemptive scheduling in SI; design plans as interruptible sequences.

---

Worked Examples

Example 1: Multi-Agent Task Allocation with Plan Conflicts

Scenario: Two agents (A1, A2) coordinate to achieve deliver(package, destination). Both have plans but different capabilities.

Initial State:

• A1 beliefs: location(A1, warehouse), can_carry(A1, small_items), location(package, warehouse)
• A2 beliefs: location(A2, depot), can_carry(A2, any), has_vehicle(A2)
• Shared belief: size(package, large), destination(customer_site)

Event: +!deliver(package, customer_site) posted to both agents

Decision Process:

1. A1 Plan Selection (SO):

   • Plan P1: +!deliver(X,Y) : can_carry(A1,small_items) & size(X,small) <- pickup(X); transport(X,Y)
   • Context guard fails: size(package,large) contradicts size(X,small)
   • No applicable plans → posts plan_failure(deliver, no_capability)

2. A2 Plan Selection (SO):

   • Plan P2: +!deliver(X,Y) : can_carry(A2,any) & has_vehicle(A2) <- pickup(X); drive(X,Y); dropoff(X)
   • Context guard succeeds → P2 selected
   • Creates intention I1: [pickup(package), drive(package,customer_site), dropoff(package)]

3. A1 Belief Update:

   • Receives message: attempting(A2, deliver, package)
   • Updates beliefs: +delegated(deliver, package, A2)
   • Drops failed intention

Novice Error: Would have both agents attempt delivery, creating resource conflicts. Expert Insight: Coordination happens through belief sharing and plan context guards, not hardcoded agent knowledge.

Example 2: Interrupt Handling with Intention Reconsideration

Scenario: Agent executing long-running data processing task receives urgent security alert.

Initial State:

• Active intention I1: [process_batch(data1), process_batch(data2), generate_report()]
• Current execution: middle of process_batch(data1) (will take 10 more minutes)

Event: +security_alert(intrusion_detected, server_3)

Decision Process:

1. Event Selection (SE):

   • SE priorities: security_events > routine_processing
   • security_alert selected over continuing I1

2. Plan Selection (SO):

   • Plan P3: +security_alert(Type,Location) : has_admin_access <- isolate_system(Location); notify_team(Type)
   • Context guard satisfied → P3 selected
   • Creates intention I2: [isolate_system(server_3), notify_team(intrusion_detected)]

3. Intention Scheduling (SI):

   • Current intentions: I1 (suspended at process_batch(data1)), I2 (new, urgent)
   • SI policy: security intentions preempt processing intentions
   • Selects I2 for execution

4. Execution:

   • Executes isolate_system(server_3) immediately
   • Executes notify_team(intrusion_detected)
   • I2 completes, drops from intention set

5. Resumption:

   • Only I1 remains: [process_batch(data1), process_batch(data2), generate_report()]
   • Resumes process_batch(data1) from suspension point

Novice Error: Would either ignore the security alert or abandon the processing task entirely. Expert Insight: Intention suspension preserves progress while enabling responsive behavior. SI scheduling policy is explicit and configurable.

---

Quality Gates

• [ ] Agent architecture has explicit SE, SO, SI selection functions with documented policies
• [ ] Each plan has well-defined triggering event and context guard that can be evaluated against current beliefs
• [ ] Plan library includes failure-handling plans for each major plan type (not just success paths)
• [ ] Belief update mechanism can handle contradictory information and propagate changes to active intentions
• [ ] Multiple intentions can be active concurrently with clear scheduling/preemption rules
• [ ] Event queue processing is prioritized (not FIFO) with explicit priority assignment
• [ ] Plan failure triggers events rather than system crashes or silent failures
• [ ] Context guards are mutually exclusive OR plan selection is explicitly ordered to avoid non-determinism
• [ ] Agent can explain its actions by exposing intention stack and triggering events
• [ ] System performance degrades gracefully under high event load (no infinite loops or stack overflow)

---

NOT-FOR Boundaries

NOT FOR: Simple rule-based systems where all behavior is reactive (no persistent goals) → USE INSTEAD: Basic rule engine or event-action system

NOT FOR: Static planning problems where environment doesn't change during execution
→ USE INSTEAD: Classical planners (A*, STRIPS, HTN)

NOT FOR: Real-time systems requiring guaranteed response times or hard deadlines → USE INSTEAD: Real-time scheduling systems with timing analysis

NOT FOR: Systems where all coordination can be handled by a central controller → USE INSTEAD: Workflow orchestration or centralized task queuing

NOT FOR: Pure data transformation pipelines with no autonomous decision-making → USE INSTEAD: ETL tools, stream processing frameworks

NOT FOR: Applications requiring machine learning or statistical inference as primary capability → USE INSTEAD: ML frameworks with BDI as coordination layer if needed