Plugin Architecture
What can be replaced
Models, Session storage, memory, tool catalogs and executors, Skill loading, context reduction, scheduling, jobs, sandbox providers, protocol adapters, and observability sinks have explicit extension boundaries.
An ExtensionRegistration supplies identity, capability/API version, configuration schema, dependencies, scope, and the factory for a working implementation. The extension kernel resolves dependencies, validates configuration, rolls back failed startup, and closes scopes in reverse dependency order.
How hosts compose providers
- Use
SAgentBuilder().with_defaults(...)for standard providers. - Select plugin bindings in the manifest’s
runtime.capabilities. - Inject host-owned providers through Builder methods such as
with_model_provider,with_session_store, orwith_tool_runtime. - Build once, inspect
application.resolved_plan, and close the application when the host shuts down.
Installed extensions can use the sage.extensions Python entry-point group. Source plugins require explicit host trust and authorization; they are executable host code, not an isolation mechanism.
What plugins cannot redefine
Legal lifecycle transitions, canonical event ordering, and Session history authority are framework contracts. A plugin must advertise only guarantees it enforces. A database-backed store does not automatically provide cross-process subscriptions, distributed claims, or durable jobs.
Manifest configuration · Extension contracts · Integration examples