agenticstack 0.2.0

The WordPress of AI Agents - A modular, lightweight agentic framework

AgenticStack

Agents you install, not build.

AgenticStack is an open, Apache-2.0 agent runtime with typed capability contracts, permissioned plugins, and a marketplace where working agents are one command away.

pip install agenticstack
stack agent install docs-qa     # shows permissions, verifies sha256
stack run docs-qa               # prompts live in ./agents/docs-qa — edit freely

That's the whole pitch: a working agent in two commands, unpacked as an editable bundle — open its prompt files, drop documents into its knowledge/ folder, make it yours. The WordPress model, for agents.

---

Why AgenticStack (the honest version)

Plenty of good frameworks orchestrate agents. AgenticStack is different in five specific, checkable ways:

1. Typed capability contracts with shipped conformance suites. Memory, vector stores, providers, retrieval, and guards are typed contracts (agenticstack.api), each with a pytest conformance suite the framework itself passes in CI. A plugin author subclasses one fixture; a green suite is a proof of compatibility, not a promise. No other open framework ships this.

# tests/test_conformance.py — this is a plugin's entire proof
import pytest
from agenticstack.testing import MemoryContract
from my_plugin import MyMemory

class TestMyMemoryConformance(MemoryContract):
    @pytest.fixture
    def memory(self):
        return MyMemory()

2. Permissions before anything runs. Every plugin and agent declares network / filesystem / shell / env in its agentstack.toml manifest. You see the request at install; the runtime refuses to load anything you haven't granted — enforced before a single line of plugin code executes. (Loaded code runs with process privileges — this is a guardrail and an audit surface, not a sandbox. We say so plainly; see SECURITY.md.)

3. Packaged agents as products. Agents ship as .stack bundles: prompts, optional skills, eval fixtures, a knowledge folder — versioned, sha256-verified, installed into your project where you can read and edit everything. Publishing one requires ≥5 passing eval fixtures (stack agent eval).

4. Tools that defend themselves. Our HTTP tool blocks SSRF by checking resolved addresses (including IPv4-mapped IPv6, cloud-metadata endpoints, and every redirect hop). Our SQL tool is read-only at the engine level via SQLite's authorizer callback — not a substring blacklist. Our filesystem tools resolve symlinks before deciding a path is inside the sandbox. Each control is tested adversarially, and the residual gaps (DNS rebinding, TOCTOU) are documented rather than hidden.

5. A neutral marketplace. The registry is a static, CDN-served index over PyPI and publisher releases — open metadata, yank kill-switch, security advisories (stack plugin audit), verified publishers. No cloud gravity: the core never phones home, and there is no hosted tier the framework nudges you into.

Quickstart in code

from agenticstack import Agent, skill

@skill(id="greet", description="Greet the user")
async def greet(name: str) -> str:
    return f"Hello, {name}!"

agent = Agent(
    name="Greeter",
    skills=[greet],
    model="gpt-4o-mini",        # provider inferred; 12 providers supported
    memory="sqlite",            # capability name -> resolved from installed plugins
    guards=["pii", "secrets"],  # same for guards
)
print(agent.run("Say hi to Ada"))

Capabilities resolve by name through the plugin registry — swap sqlite for any installed memory backend without touching agent code. Providers get retry/backoff/timeouts; the tool loop chains multi-step tool calls; agent.stream() streams. Also built in:

from pydantic import BaseModel
from agenticstack import FallbackProvider

class Invoice(BaseModel):
    total: float
    currency: str

invoice = await agent.chat_structured("Bill: 3 units at $12", model=Invoice)
agent = Agent(name="Resilient", provider=FallbackProvider(["openai", "anthropic"]))

The catalog — every package is ours

No wrappers around other frameworks. Each plugin is first-party code implementing a typed contract, with its own conformance or adversarial tests and a declared permission set.

Package	Kind	What it does
agenticstack-vectorstore-chroma	plugin	ChromaDB vector store (persistent or in-memory)
agenticstack-vectorstore-qdrant	plugin	Qdrant — in-memory, local, or remote; passes the full contract against the real client
agenticstack-vectorstore-pgvector	plugin	PostgreSQL/pgvector — hand-written SQL, injection-hardened identifiers
agenticstack-memory-sqlite	plugin	SQLite long-term memory with FTS5 search, zero deps
agenticstack-loaders	plugin	PDF (per-page), DOCX (sections + tables), HTML, web fetch, same-origin crawl
agenticstack-tools-web	plugin	HTTP client with real SSRF defense, pluggable web search, page-to-text
agenticstack-tools-data	plugin	Read-only SQL (engine authorizer), sandboxed filesystem, CSV querying
agenticstack-tools-essentials	plugin	Safe skills pack: calculator, dates, text utilities
agenticstack-guard-secrets	plugin	Redacts API keys/tokens/credentials from agent traffic
agenticstack-hitl	plugin	Approvals, review queues, feedback collection, intervention points
agenticstack-dashboard	plugin	Live local dashboard of plugins, hooks, and agent activity
agenticstack-costs	plugin	Per-agent token/cost tracking with budget warnings
agenticstack-transcripts	plugin	JSONL audit transcripts of every run, tool call, and error
agenticstack-cache	plugin	LLM response caching (in-memory LRU or SQLite) as a provider wrapper
docs-qa	agent	Answers strictly from your documents, with citations
code-reviewer	agent	Severity-ranked code review with checklist skills
support-bot	agent	Ticket triage with escalation rules
invoice-bot	agent	Invoicing and margin math that shows its work
standup-scribe	agent	Turns raw notes into standup summaries (prompt-only bundle)

pip install "agenticstack[full]"   # the whole catalog

Browse them in the marketplace — a static site over the same index.json the CLI reads.

Agent architectures

Four executing reasoning patterns, not scaffolding — each emits the standard hooks, so cost tracking and transcripts work unchanged:

from agenticstack import ReActAgent, PlanExecuteAgent, ReflectionAgent, SubAgentDelegator

result = await ReActAgent(agent).run("Research X and summarize")
result.trace          # (thought, action, observation) per step
result.usage          # tokens/cost for the whole run

Pattern	What it does
ReActAgent	Thought → Action → Observation with an inspectable trace and graceful step-limit fallback
PlanExecuteAgent	Plans, then executes dependency-ordered steps with replanning on failure
ReflectionAgent	Draft → critique → revise until a score threshold or iteration cap
SubAgentDelegator	Supervisor delegating to named specialists, concurrently, with a depth cap

Build a plugin in 15 minutes

stack plugin create mymemory --capability memory
cd agenticstack-memory-mymemory && pip install -e ".[dev]"
stack plugin validate     # manifest lint + conformance suite + import-time check
stack plugin publish      # PyPI + registry PR

The failing conformance tests are the spec — implement until green. Full tutorial: docs/plugins/write-a-memory-plugin.md · manifest reference: docs/reference/agentstack-toml.md

Build an agent bundle

stack agent create my-bot --template docs-qa
# edit prompts/system.md, drop files into knowledge/
stack agent eval my-bot      # fixture-based checks, pass/fail table + cost
stack agent pack my-bot      # -> my-bot-0.1.0.stack + sha256

Architecture (one paragraph)

A thin core — kernel (events/config/lifecycle), agenticstack.api (the contract surface, versioned as API_VERSION), and one plugin runtime (agentstack.toml manifests, DISCOVERED → RESOLVED → LOADED → ACTIVE with dependency/version/permission gating at RESOLVED) — beneath first-party capability packages and agent bundles. Agents are wired through public hook points (agent.before_run, before_llm_call, before_tool_call, …), and the built-in memory, RAG, guard, and tracing integrations attach through the same hooks and registries a marketplace plugin uses. Also in the box: graph-based StateGraph workflows, 12 LLM providers, and offline license validation for paid plugins (agenticstack[commerce]). Human oversight — approvals, review queues, feedback, intervention points — is now an opt-in first-party plugin (pip install agenticstack-hitl), included in agenticstack[full].

Status

v0.2 (alpha). APIs may change until the contracts freeze (then changes go through the contract-RFC process). The test suite — including per-capability conformance suites the built-ins must pass — runs in CI on Python 3.11–3.13. Migrating from v0.1: MIGRATION.md.

Contributing

• CONTRIBUTING.md — DCO sign-off, dev setup, plugin-vs-core guide
• GOVERNANCE.md — BDFL + contract RFCs (14-day window)
• SECURITY.md — private reporting, 72h acknowledgement
• The fastest way to contribute: publish a plugin. The registry's 90-day goal is one external plugin passing a conformance suite.

License

Apache-2.0. The AgenticStack name and logo are trademarks; see NOTICE.