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:
-
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)
-
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)]
-
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:
-
Event Selection (SE):
- SE priorities: security_events > routine_processing
security_alert selected over continuing I1
-
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)]
-
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
-
Execution:
- Executes
isolate_system(server_3) immediately
- Executes
notify_team(intrusion_detected)
- I2 completes, drops from intention set
-
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
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