skills/bdi-agency-model/SKILL.md
BDI (Beliefs-Desires-Intentions) agency framework for designing autonomous agents with mental state architectures
npx skillsauth add curiositech/windags-skills bdi-agency-modelInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
license: Apache-2.0
Load this skill when facing:
This skill applies beyond robotics/AI agents—it's relevant for any system that must make decisions over time with partial information, including business process systems, game AI, automated trading, and organizational design.
Beliefs (informational state), Desires (motivational state), and Intentions (deliberative state) aren't philosophical conveniences—they're architectural necessities for resource-bounded agents in dynamic environments.
Why separate? Because conflating them creates impossible computational requirements:
The separation enables local updates and selective reasoning.
The core tension:
The empirical finding (bold vs. cautious agents):
Rational commitment = maintaining intentions until there's sufficient reason to reconsider, where "sufficient" depends on environment dynamics and computational costs.
Task-oriented systems: Execute procedures without maintaining why
Goal-oriented systems: Maintain explicit desired states and plans to achieve them
The gap: Most software is task-oriented. BDI provides the minimal architecture for goal-orientation.
Intentions don't just represent commitments—they actively constrain future reasoning:
This is not bounded rationality or satisficing—it's a rational strategy for resource-bounded agents. The alternative (consider all options always) is computationally intractable.
BDI (philosophy/logic tradition) and Soar (cognitive psychology tradition) independently converged on isomorphic architectures:
| BDI Component | Soar Component | Computational Role | |---------------|----------------|-------------------| | Beliefs | States | World representation | | Desires | Subgoals | Motivational targets | | Intentions | Operators | Chosen actions | | Plans | Problem spaces | Action sequences |
Implication: These components aren't arbitrary design choices but discovered necessities—like multiple cultures independently inventing the wheel. Any system facing similar constraints (bounded resources, partial information, dynamic environments, real-time action) will need similar structures.
IF environment is highly static THEN bias toward bold commitment (rarely reconsider) IF environment is highly dynamic THEN bias toward cautious reconsideration (frequently reevaluate)
IF computational resources abundant THEN can afford more frequent reconsideration IF computational resources scarce THEN must commit more strongly to amortize planning cost
IF action execution is expensive THEN reconsider before acting IF deliberation is expensive THEN commit and act quickly
IF new information directly contradicts intention's preconditions THEN reconsider immediately IF new information merely opens alternatives THEN reconsider only if significantly better
IF system must act in real-time THEN needs intentions (can't replan from desires every cycle) IF system faces conflicting goals THEN needs desire/intention distinction (desires can conflict, intentions cannot) IF system must coordinate with others THEN needs explicit intentions (for commitment communication) IF system must explain behavior THEN needs all three (explain actions via intentions, intentions via desires, desires via beliefs) IF system must adapt to failures THEN needs goal-oriented representation (to find alternative means)
IF environment is static AND goals are clear AND plans rarely fail THEN task-oriented architecture may suffice IF environment changes OR goals conflict OR plans frequently fail THEN need BDI-style architecture IF multiple agents must coordinate THEN need explicit commitment mechanisms (load multi-agent reference) IF system must learn from experience THEN need BDI + learning extensions (load learning reference)
| Reference File | Load When... | Key Content |
|----------------|--------------|-------------|
| why-beliefs-desires-intentions-exist.md | Justifying architectural decisions; explaining why three components are necessary | Detailed computational argument for BDI separation; what each component solves; costs of conflation |
| rational-commitment-and-reconsideration.md | Designing reconsideration strategies; debugging thrashing or stubbornness | Kinny-Georgeff experiments; bold vs. cautious agents; meta-level control; empirical results |
| task-vs-goal-orientation.md | Comparing architecture approaches; explaining need for goal representation | Deep dive on task/goal distinction; recovery capabilities; opportunistic replanning; explainability |
| soar-bdi-convergent-evolution.md | Validating design choices; comparing with cognitive architectures | Soar-BDI mapping; convergent evolution argument; universal principles; cross-tradition insights |
| multi-agent-commitment-and-coordination.md | Designing multi-agent systems; coordination protocols | Joint intentions; social commitments; team reasoning; coordination mechanisms; distributed BDI |
| learning-the-missing-piece.md | Adding adaptation; integrating ML with planning | BDI limitations; learning integration strategies; experience-based improvement; open challenges |
Symptom: System constantly reconsiders all options, thrashes between plans, never completes actions Root cause: Treating every belief update as requiring complete replanning (classical decision theory mistake) BDI insight: Rational commitment means maintaining intentions despite minor belief changes
Symptom: System continues executing plan after goal achieved or becomes impossible Root cause: Task-oriented architecture without goal representation BDI insight: Maintain explicit relationship between intentions, plans, and desires to enable goal-aware execution
Symptom: System tries to pursue conflicting goals simultaneously, resources spread too thin Root cause: Not distinguishing between "would like to achieve" and "committed to pursuing" BDI insight: Desires can conflict; intentions cannot (must resolve conflicts during deliberation)
Symptom: System abandons plans at first difficulty; erratic, unpredictable behavior Root cause: Treating intentions as weak preferences rather than commitments BDI insight: Intentions constrain future reasoning—they're not just goals but committed goals
Symptom: System fails when environment changes; no recovery from failures Root cause: Conventional software approach (plan = fixed procedure) BDI insight: Plans must be monitored against goals; reconsideration needed when environment dynamics high
Symptom: Fixed reconsideration strategy fails across different environment dynamics Root cause: Not adapting commitment strategy to environment characteristics BDI insight: Need meta-level reasoning about when to reconsider (the central open problem)
Symptom: Coordination failures; agents undermine each other's plans Root cause: Using individual BDI without social commitment mechanisms BDI insight: Multi-agent requires joint intentions and commitment communication protocols
Key diagnostic question: "Why can't you just merge desires and intentions?"
tools
Building resilient distributed systems with circuit breakers, retries with full-jitter exponential backoff, retry budgets (per-request 3-attempt + per-client 10% ratio per Google SRE), deadline propagation, and the cascading-failure math (4 layers × 3 retries = 64x amplification). Grounded in Resilience4j, Microsoft Cloud Patterns, AWS Architecture Blog (Marc Brooker), and Google SRE Book.
testing
Designing HTTP cache headers that work correctly across browsers, CDNs, and shared proxies — `Cache-Control` directives per RFC 9111, `stale-while-revalidate` and `stale-if-error` per RFC 5861, the Vary header for varying responses, and surrogate keys for tag-based purging. Grounded in IETF RFCs and Cloudflare/Fastly docs.
development
Use when designing or fixing a Content Security Policy on a real site, choosing between nonce-based and hash-based CSP, adding strict-dynamic, debugging "Refused to execute inline script" errors, deploying CSP in report-only mode first, configuring report-to / report-uri, or auditing an existing policy for unsafe-inline / unsafe-eval / wildcards. Triggers: "CSP blocks legitimate inline script", strict-dynamic, nonce-{RANDOM}, sha256-{HASH}, object-src none, base-uri none, frame-ancestors, Trusted Types, X-Content-Security-Policy obsolete, report-only vs enforced. NOT for general HTTP security headers (HSTS, COOP/COEP), Trusted Types deep dive, CORS configuration, or building a WAF.
tools
Choosing and operating an HTTP API versioning strategy that doesn't break clients — Stripe's date-based pinned versions, the Deprecation/Sunset header pair (RFC 9745 + RFC 8594), URI vs header vs media-type approaches, and the version-transformer pattern. Grounded in Stripe's published architecture and IETF RFCs.