How It Works
Quick Start
1
Run YAML — framework auto-detected
ag2 is registered and can be requested explicitly via --framework ag2 or framework: ag2 in YAML, but it is not part of the auto-detect chain because its adapter is an unimplemented stub. Selecting it explicitly will raise NotImplementedError at run time until a full implementation lands.When none of the supported framework adapters are installed (e.g. a container that ships only
praisonai without the crewai / autogen / praisonaiagents extras), the auto-detect chain raises RuntimeError: No supported framework installed. Available adapters: []. This is the intended, actionable failure — install one of the adapters (pip install praisonai[crewai], pip install praisonai[autogen], or pip install praisonaiagents) and re-run.2
Probe before selecting a framework
API Reference
Known Probe Names
The following framework names are supported:google_adk detection uses a three-step probe in _google_adk_probe(): (1) importlib.metadata.distribution("google-adk") — the PyPI dist must be installed; (2) importlib.util.find_spec("google.adk") — the namespace must be discoverable; (3) from google.adk.agents import Agent with fallback to from google.adk import Agent. All three must succeed for is_available("google_adk") to return True. Install with pip install 'praisonai-frameworks[google-adk]' or pip install 'praisonai[google-adk]'.praisonai.adapters.vector_stores calls is_available("chromadb") / is_available("pinecone") rather than maintaining its own _check_* helpers.
autogen_v2 is an adapter name registered in FrameworkAdapterRegistry, not a probe name in _framework_availability. The probe name remains autogen (it imports the autogen v0.2 package). Use the adapter’s .is_available() method to test whether a specific adapter will dispatch successfully — it folds in the implemented marker.Adapter Availability vs Framework Availability
Two distinct concepts affect whether an AutoGen-family adapter will actually work:
For AutoGen v0.4 and AG2 today: the package may import successfully, but the adapter still reports
False because implemented = False. This is the safety-by-default behaviour added in PR #2086.
AG2 Detection Quirk
AG2 ships under theautogen namespace, so is_available("ag2") checks both:
importlib.metadata.distribution('ag2')- Ensures AG2 distribution is installedimportlib.util.find_spec("autogen")- Ensuresautogennamespace is importable
Cache Management (module-level probes)
These semantics apply topraisonai._framework_availability.is_available() — the low-level, per-package probe. The higher-level FrameworkAdapterRegistry.is_available() used by pick_default() and list_available_frameworks() follows the TTL rules in the next section.
Results are cached indefinitely until explicitly invalidated:
Cache Management (adapter registry)
FrameworkAdapterRegistry.is_available(name) caches results so hot-path callers (pick_default, list_available_frameworks) do not re-probe. Only positives and structural failures are pinned for the process; every other negative is transient and expires after a 30-second cool-down (_avail_retry_cooldown) so a mid-life pip install is picked up without a restart (PraisonAI PR #5307).
Mid-life install recovery:
praisonai serve / long-running daemons no longer need a restart after pip install 'praisonai[crewai]'. The registry re-probes any transient negative after ~30 s (_avail_retry_cooldown) and invalidates the process-wide _framework_availability cache before re-probing, so both cache tiers see the newly-installed dep on the next call.registry.invalidate_availability(name) (or with no argument) to force a reprobe sooner.
Thread Safety
The availability checker uses double-checked locking underthreading.Lock for thread-safe caching:
Custom Adapter Usage
Plugin authors can use_framework_availability for their is_available() implementations:
Testing Support
Useinvalidate() in tests that mock importlib:
Backward-compat constants on praisonai.agents_generator
Six module-level constants are available for backward compatibility and can be imported directly from praisonai.agents_generator.
For new code, use
is_available("crewai") directly rather than importing these constants.
The parallel wrapper accessor
praisonai.inbuilt_tools.PRAISONAI_TOOLS_AVAILABLE also delegates to is_available("praisonai_tools") (PR #5318 aligned it with this single source of truth; prior to that PR the wrapper always returned True).Best Practices
Prefer adapter.is_available() for dispatch decisions
Prefer adapter.is_available() for dispatch decisions
Package probes (
is_available("autogen_v4")) only confirm importability. Use AutoGenV4Adapter().is_available() when you need to know whether execution will actually succeed.Use invalidate() in tests that mock importlib
Use invalidate() in tests that mock importlib
Cached results persist for the process lifetime. Call
invalidate() before and after monkey-patching importlib so probes re-run cleanly.Avoid heavy imports inside is_available()
Avoid heavy imports inside is_available()
Custom adapters should delegate to
is_available() rather than importing large packages on every CLI startup probe.Use pick_default() instead of manual priority lists
Use pick_default() instead of manual priority lists
For default framework selection, call
FrameworkAdapterRegistry.pick_default() rather than hard-coding probe tuples.Related
Framework Adapter Plugins
Creating custom framework adapters
AutoGen Framework
AutoGen framework integration
Google ADK Framework
Google ADK framework integration

