agentforge-py 0.2.3__tar.gz → 0.3.0__tar.gz

{agentforge_py-0.2.3 → agentforge_py-0.3.0}/.gitignore

@@ -47,3 +47,13 @@ Thumbs.db
 # Project-local
 *.local
 .agentforge-state/.session-cache
+
+# AI-assistant working state — local session tracking, not part of
+# the published project. The process docs under .claude/ (standards,
+# checklists, CLAUDE.md) are intentionally kept tracked; only the
+# churny per-session state files are ignored.
+.claude/state/
+
+# Launch / go-to-market drafts — local-only marketing material,
+# never published to the repo.
+launch/

agentforge_py-0.3.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: agentforge-py
+Version: 0.3.0
+Summary: AgentForge — open-source plug-and-play framework for production AI agents
+Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Documentation, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Changelog, https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Scaffoldic/agentforge-py/issues
+Author: The AgentForge Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agentic,ai,framework,llm,react,tools
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: agentforge-core~=0.3.0
+Requires-Dist: copier>=9.4
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.15
+Provides-Extra: a2a
+Requires-Dist: agentforge-a2a~=0.3.0; extra == 'a2a'
+Provides-Extra: all
+Requires-Dist: agentforge-a2a~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-anthropic[anthropic]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-bedrock~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-chat-history-postgres~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-chat-history-redis~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-chat-http~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-chat-slack~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-chat~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-eval-geval~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-evidently[evidently]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-guard-llamaguard~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-guard-llmguard~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-guard-nemo~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-guard-presidio~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-langfuse[langfuse]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-litellm[litellm]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-mcp[mcp]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-memory-neo4j~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-memory-postgres~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-memory-sqlite~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-memory-surrealdb~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-ollama[ollama]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-openai[openai]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-otel~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-phoenix[phoenix]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-reranker-cohere[cohere]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-reranker-mixedbread[mixedbread]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-reranker-sentence-transformers[sentence-transformers]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-reranker-voyage[voyage]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-statsd[statsd]~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-testing~=0.3.0; extra == 'all'
+Requires-Dist: agentforge-voyage[voyage]~=0.3.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: agentforge-anthropic[anthropic]~=0.3.0; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: agentforge-bedrock~=0.3.0; extra == 'bedrock'
+Provides-Extra: chat
+Requires-Dist: agentforge-chat~=0.3.0; extra == 'chat'
+Provides-Extra: chat-history-postgres
+Requires-Dist: agentforge-chat-history-postgres~=0.3.0; extra == 'chat-history-postgres'
+Provides-Extra: chat-history-redis
+Requires-Dist: agentforge-chat-history-redis~=0.3.0; extra == 'chat-history-redis'
+Provides-Extra: chat-http
+Requires-Dist: agentforge-chat-http~=0.3.0; extra == 'chat-http'
+Provides-Extra: chat-slack
+Requires-Dist: agentforge-chat-slack~=0.3.0; extra == 'chat-slack'
+Provides-Extra: eval
+Requires-Dist: agentforge-eval-geval~=0.3.0; extra == 'eval'
+Provides-Extra: evidently
+Requires-Dist: agentforge-evidently[evidently]~=0.3.0; extra == 'evidently'
+Provides-Extra: guard-llamaguard
+Requires-Dist: agentforge-guard-llamaguard~=0.3.0; extra == 'guard-llamaguard'
+Provides-Extra: guard-llmguard
+Requires-Dist: agentforge-guard-llmguard~=0.3.0; extra == 'guard-llmguard'
+Provides-Extra: guard-nemo
+Requires-Dist: agentforge-guard-nemo~=0.3.0; extra == 'guard-nemo'
+Provides-Extra: guard-presidio
+Requires-Dist: agentforge-guard-presidio~=0.3.0; extra == 'guard-presidio'
+Provides-Extra: langfuse
+Requires-Dist: agentforge-langfuse[langfuse]~=0.3.0; extra == 'langfuse'
+Provides-Extra: litellm
+Requires-Dist: agentforge-litellm[litellm]~=0.3.0; extra == 'litellm'
+Provides-Extra: mcp
+Requires-Dist: agentforge-mcp[mcp]~=0.3.0; extra == 'mcp'
+Provides-Extra: memory-neo4j
+Requires-Dist: agentforge-memory-neo4j~=0.3.0; extra == 'memory-neo4j'
+Provides-Extra: memory-postgres
+Requires-Dist: agentforge-memory-postgres~=0.3.0; extra == 'memory-postgres'
+Provides-Extra: memory-sqlite
+Requires-Dist: agentforge-memory-sqlite~=0.3.0; extra == 'memory-sqlite'
+Provides-Extra: memory-surrealdb
+Requires-Dist: agentforge-memory-surrealdb~=0.3.0; extra == 'memory-surrealdb'
+Provides-Extra: ollama
+Requires-Dist: agentforge-ollama[ollama]~=0.3.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: agentforge-openai[openai]~=0.3.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: agentforge-otel~=0.3.0; extra == 'otel'
+Provides-Extra: phoenix
+Requires-Dist: agentforge-phoenix[phoenix]~=0.3.0; extra == 'phoenix'
+Provides-Extra: reranker-cohere
+Requires-Dist: agentforge-reranker-cohere[cohere]~=0.3.0; extra == 'reranker-cohere'
+Provides-Extra: reranker-mixedbread
+Requires-Dist: agentforge-reranker-mixedbread[mixedbread]~=0.3.0; extra == 'reranker-mixedbread'
+Provides-Extra: reranker-sentence-transformers
+Requires-Dist: agentforge-reranker-sentence-transformers[sentence-transformers]~=0.3.0; extra == 'reranker-sentence-transformers'
+Provides-Extra: reranker-voyage
+Requires-Dist: agentforge-reranker-voyage[voyage]~=0.3.0; extra == 'reranker-voyage'
+Provides-Extra: statsd
+Requires-Dist: agentforge-statsd[statsd]~=0.3.0; extra == 'statsd'
+Provides-Extra: testing
+Requires-Dist: agentforge-testing~=0.3.0; extra == 'testing'
+Provides-Extra: voyage
+Requires-Dist: agentforge-voyage[voyage]~=0.3.0; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# agentforge
+
+The default runtime for the AgentForge framework — `Agent`, `ReActLoop`,
+default tools, `SimpleFinding`, in-memory store, basic safety defaults,
+`BudgetPolicy`. Most users install this package and add module extras
+as needed.
+
+## Three-line agent (once feat-001 lands)
+
+```python
+from agentforge import Agent
+
+agent = Agent(model="anthropic:claude-sonnet-4.7")
+result = await agent.run("Say hello in three words.")
+```
+
+## Install
+
+```bash
+pip install agentforge-py                              # core runtime
+pip install "agentforge-py[anthropic]"                 # + Anthropic provider
+pip install "agentforge-py[anthropic,memory-postgres]" # + persistence
+```
+
+## Status
+
+v0.0 — pre-alpha. Repo bootstrapped; feat-001 (Core contracts &
+`Agent` orchestrator) is the next milestone.
+
+## License
+
+Apache 2.0.

agentforge_py-0.3.0/pyproject.toml

@@ -0,0 +1,189 @@
+# agentforge — default runtime + prebuilt for the AgentForge framework.
+#
+# This package ships the sane defaults a developer expects on a fresh
+# install: the `Agent` orchestrator, `ReActLoop` (stable reasoning
+# strategy), the four built-in tools, the `SimpleFinding` variant +
+# scorecard renderer, the in-memory MemoryStore, the basic safety
+# defaults, and the BudgetPolicy.
+#
+# This package depends on `agentforge-core` (locked contracts) and
+# nothing else from the AgentForge family. Optional extras pull in
+# specific provider/persistence/observability modules.
+#
+# Per ADR-0003 (three-tier package model — this is Tier 2).
+
+[project]
+name = "agentforge-py"
+version = "0.3.0"
+description = "AgentForge — open-source plug-and-play framework for production AI agents"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    {name = "The AgentForge Authors"},
+]
+keywords = ["ai", "agent", "llm", "framework", "agentic", "react", "tools"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "agentforge-core ~= 0.3.0",
+    "pydantic>=2.10",
+    "pyyaml>=6.0",
+    "typer>=0.15",
+    # feat-011: Copier is the scaffolding + three-way-merge engine
+    # (ADR-0005). Used by `agentforge new` / `agentforge upgrade`.
+    "copier>=9.4",
+]
+
+# Optional extras — names match the underlying provider/module package.
+# Adding a module via `pip install "agentforge[<name>]"` pulls the
+# corresponding package onto the path; entry-point discovery does the
+# rest (per ADR-0004).
+[project.optional-dependencies]
+# Each extra installs one sister package at the matching coordinated
+# release-train version. `pip install agentforge-py[anthropic]`
+# resolves to `agentforge-py + agentforge-anthropic`, etc.
+# Add a new entry here every time a new sister package ships.
+
+# LLM providers. Where a sister package keeps its vendor SDK behind
+# an optional `[<sdk>]` extra (the lazy-import pattern), the meta extra
+# MUST chain that extra — otherwise `pip install "agentforge-py[x]"`
+# installs the wrapper but not the SDK and the first call raises a
+# ModuleError (bug-015). bedrock hard-deps its SDK (aioboto3/botocore),
+# so it requests no extra — and must NOT request a phantom `[bedrock]`.
+anthropic = ["agentforge-anthropic[anthropic] ~= 0.3.0"]
+openai = ["agentforge-openai[openai] ~= 0.3.0"]
+bedrock = ["agentforge-bedrock ~= 0.3.0"]
+ollama = ["agentforge-ollama[ollama] ~= 0.3.0"]
+litellm = ["agentforge-litellm[litellm] ~= 0.3.0"]
+
+# Embeddings
+voyage = ["agentforge-voyage[voyage] ~= 0.3.0"]
+
+# Memory backends (each hard-deps its driver SDK — no extra to chain)
+memory-sqlite = ["agentforge-memory-sqlite ~= 0.3.0"]
+memory-postgres = ["agentforge-memory-postgres ~= 0.3.0"]
+memory-neo4j = ["agentforge-memory-neo4j ~= 0.3.0"]
+memory-surrealdb = ["agentforge-memory-surrealdb ~= 0.3.0"]
+
+# Chat surface (chat hard-deps aiosqlite; history backends hard-dep their SDK)
+chat = ["agentforge-chat ~= 0.3.0"]
+chat-http = ["agentforge-chat-http ~= 0.3.0"]
+chat-slack = ["agentforge-chat-slack ~= 0.3.0"]
+chat-history-postgres = ["agentforge-chat-history-postgres ~= 0.3.0"]
+chat-history-redis = ["agentforge-chat-history-redis ~= 0.3.0"]
+
+# Rerankers
+reranker-cohere = ["agentforge-reranker-cohere[cohere] ~= 0.3.0"]
+reranker-voyage = ["agentforge-reranker-voyage[voyage] ~= 0.3.0"]
+reranker-mixedbread = ["agentforge-reranker-mixedbread[mixedbread] ~= 0.3.0"]
+reranker-sentence-transformers = ["agentforge-reranker-sentence-transformers[sentence-transformers] ~= 0.3.0"]
+
+# Guardrails (each hard-deps its SDK — no extra to chain)
+guard-llmguard = ["agentforge-guard-llmguard ~= 0.3.0"]
+guard-presidio = ["agentforge-guard-presidio ~= 0.3.0"]
+guard-nemo = ["agentforge-guard-nemo ~= 0.3.0"]
+guard-llamaguard = ["agentforge-guard-llamaguard ~= 0.3.0"]
+
+# Observability
+langfuse = ["agentforge-langfuse[langfuse] ~= 0.3.0"]
+phoenix = ["agentforge-phoenix[phoenix] ~= 0.3.0"]
+otel = ["agentforge-otel ~= 0.3.0"]
+statsd = ["agentforge-statsd[statsd] ~= 0.3.0"]
+evidently = ["agentforge-evidently[evidently] ~= 0.3.0"]
+
+# Protocols
+mcp = ["agentforge-mcp[mcp] ~= 0.3.0"]
+a2a = ["agentforge-a2a ~= 0.3.0"]
+
+# Eval
+eval = ["agentforge-eval-geval ~= 0.3.0"]
+
+# Testing
+testing = ["agentforge-testing ~= 0.3.0"]
+
+# Everything (development / docs / smoke-test convenience — not
+# recommended for production deploys; pick the actual integrations
+# you use to keep the dependency tree small). Vendor-SDK extras are
+# chained here too so `[all]` actually installs every SDK.
+all = [
+    "agentforge-anthropic[anthropic] ~= 0.3.0",
+    "agentforge-openai[openai] ~= 0.3.0",
+    "agentforge-bedrock ~= 0.3.0",
+    "agentforge-ollama[ollama] ~= 0.3.0",
+    "agentforge-litellm[litellm] ~= 0.3.0",
+    "agentforge-voyage[voyage] ~= 0.3.0",
+    "agentforge-memory-sqlite ~= 0.3.0",
+    "agentforge-memory-postgres ~= 0.3.0",
+    "agentforge-memory-neo4j ~= 0.3.0",
+    "agentforge-memory-surrealdb ~= 0.3.0",
+    "agentforge-chat ~= 0.3.0",
+    "agentforge-chat-http ~= 0.3.0",
+    "agentforge-chat-slack ~= 0.3.0",
+    "agentforge-chat-history-postgres ~= 0.3.0",
+    "agentforge-chat-history-redis ~= 0.3.0",
+    "agentforge-reranker-cohere[cohere] ~= 0.3.0",
+    "agentforge-reranker-voyage[voyage] ~= 0.3.0",
+    "agentforge-reranker-mixedbread[mixedbread] ~= 0.3.0",
+    "agentforge-reranker-sentence-transformers[sentence-transformers] ~= 0.3.0",
+    "agentforge-guard-llmguard ~= 0.3.0",
+    "agentforge-guard-presidio ~= 0.3.0",
+    "agentforge-guard-nemo ~= 0.3.0",
+    "agentforge-guard-llamaguard ~= 0.3.0",
+    "agentforge-langfuse[langfuse] ~= 0.3.0",
+    "agentforge-phoenix[phoenix] ~= 0.3.0",
+    "agentforge-otel ~= 0.3.0",
+    "agentforge-statsd[statsd] ~= 0.3.0",
+    "agentforge-evidently[evidently] ~= 0.3.0",
+    "agentforge-mcp[mcp] ~= 0.3.0",
+    "agentforge-a2a ~= 0.3.0",
+    "agentforge-eval-geval ~= 0.3.0",
+    "agentforge-testing ~= 0.3.0",
+]
+
+[project.scripts]
+# feat-010 ships the read-only `list` command. Destructive commands
+# (`add`, `swap`, `remove`) ship in a follow-up sub-feat alongside
+# feat-012 (Configuration system).
+agentforge = "agentforge.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/agentforge-py"
+Repository = "https://github.com/Scaffoldic/agentforge-py"
+Documentation = "https://github.com/Scaffoldic/agentforge-py"
+Changelog = "https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Scaffoldic/agentforge-py/issues"
+
+[tool.uv.sources]
+agentforge-core = { workspace = true }
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentforge"]
+# feat-011: ship Copier templates inside the wheel. The
+# `{{project_slug}}/` subdir is auto-included via the `packages`
+# directive — hatchling walks all files under src/agentforge,
+# including the Jinja2-named subdirs. Do NOT add a force-include
+# for templates: it duplicates every entry and PyPI rejects the
+# wheel with "Duplicate filename in local headers".
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/agentforge",
+    "tests",
+    "README.md",
+    "LICENSE",
+]

{agentforge_py-0.2.3 → agentforge_py-0.3.0}/src/agentforge/_tools/decorator.py

@@ -20,7 +20,15 @@ Wraps a typed function as a concrete `Tool` subclass:
 The decorator inspects the wrapped function and constructs:
 
   - `name`              from the function's `__name__` (or the
-                        `name=` override argument).
+                        `name=` override argument). Keep it within
+                        `[a-zA-Z0-9_-]` (1-64 chars): that's the
+                        tool-name charset Bedrock, OpenAI, and
+                        Anthropic all enforce, so a name outside it
+                        is rejected at request-build time with
+                        `ToolNameInvalidError` (bug-017). A plain
+                        function name like `lookup_user` is already
+                        legal; avoid dots / colons / spaces in
+                        `name=` overrides.
   - `description`       from the docstring's summary line + Args
                         section, parsed Google-style. The first
                         non-blank non-arg line is the summary;

{agentforge_py-0.2.3 → agentforge_py-0.3.0}/src/agentforge/agent.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 
 import logging
 import time
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
 from pathlib import Path
 from types import TracebackType
 from typing import Any
@@ -37,6 +37,7 @@ from agentforge_core.contracts.guardrails import (
 )
 from agentforge_core.contracts.llm import LLMClient
 from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.contracts.protocol_bridge import ProtocolBridge
 from agentforge_core.contracts.strategy import ReasoningStrategy
 from agentforge_core.contracts.tool import Tool
 from agentforge_core.observability import get_tracer
@@ -119,6 +120,7 @@ class Agent:
         tool_gates: list[ToolCallGate] | None = None,
         guardrail_policy: GuardrailPolicy | None = None,
         pipeline: Pipeline | None = None,
+        protocol_bridges: Sequence[ProtocolBridge] | None = None,
     ) -> None:
         self._config: AgentForgeConfig = load_config(config_path)
 
@@ -198,6 +200,11 @@ class Agent:
             self._pipeline_tool = PipelineFindingsTool()
             self._tools.append(self._pipeline_tool)
 
+        # feat-013: protocol handlers (e.g. MCP bridges) already started
+        # by the config builder. Their tools are passed in via `tools=`;
+        # the Agent only owns tearing them down on `close()`.
+        self._protocol_bridges: list[ProtocolBridge] = list(protocol_bridges or [])
+
         self._closed = False
 
         if install_log_filter and self._config.logging.run_id_filter:
@@ -677,6 +684,8 @@ class Agent:
         await self._memory.close()
         if self._graph_store is not None:
             await self._graph_store.close()
+        for bridge in self._protocol_bridges:
+            await bridge.close()
         uninstall_run_id_filter()
         uninstall_json_formatter()
 

{agentforge_py-0.2.3 → agentforge_py-0.3.0}/src/agentforge/cli/_build.py

@@ -20,6 +20,8 @@ deterministic exit codes (per feat-017 §4 — config invalid → 2).
 
 from __future__ import annotations
 
+import contextlib
+import inspect
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -30,6 +32,7 @@ from agentforge_core.contracts.evaluator import Evaluator
 from agentforge_core.contracts.graph_store import GraphStore
 from agentforge_core.contracts.llm import LLMClient
 from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.contracts.protocol_bridge import ProtocolBridge
 from agentforge_core.contracts.reranker import Reranker
 from agentforge_core.contracts.vector_store import VectorStore
 from agentforge_core.production.exceptions import ModuleError
@@ -73,7 +76,7 @@ async def build_agent_from_config(
     Splits out from `load_and_build` for tests + reuse — tests build
     a `AgentForgeConfig` directly and skip the YAML parse.
     """
-    memory = build_memory_from_config(config)
+    memory = await build_memory_from_config(config)
     if memory is not None:
         await _maybe_init_schema(memory)
     evaluators = build_evaluators_from_config(config)
@@ -82,26 +85,49 @@ async def build_agent_from_config(
     llm = _resolve_llm(config)
     strategy = config.agent.strategy if isinstance(config.agent.strategy, str) else None
 
-    return Agent(
-        model=llm,
-        memory=memory if memory is not None else InMemoryStore(),
-        evaluators=evaluators,
-        strategy=strategy,
-        retriever=retriever,
-        system_prompt=config.agent.system_prompt,
-        budget_usd=config.agent.budget.usd,
-        max_iterations=config.agent.max_iterations,
-        record_runs=memory if enable_recording and memory is not None else None,
-        pipeline=pipeline,
-    )
+    # feat-013 (bug-020): wire `modules.protocols` — resolve + start each
+    # handler (e.g. the MCP bridge), merge its tools with the native
+    # `agent.tools`, and hand the started bridges to the Agent so they're
+    # closed on `Agent.close()`. `build_protocols_from_config` has already
+    # awaited `start()` for every bridge it returns.
+    native_tools = build_tools_from_config(config)
+    mcp_tools, protocol_bridges = await build_protocols_from_config(config)
+    all_tools = [*native_tools, *mcp_tools]
+
+    try:
+        return Agent(
+            model=llm,
+            tools=all_tools or None,
+            memory=memory if memory is not None else InMemoryStore(),
+            evaluators=evaluators,
+            strategy=strategy,
+            retriever=retriever,
+            system_prompt=config.agent.system_prompt,
+            budget_usd=config.agent.budget.usd,
+            max_iterations=config.agent.max_iterations,
+            record_runs=memory if enable_recording and memory is not None else None,
+            pipeline=pipeline,
+            protocol_bridges=protocol_bridges,
+        )
+    except BaseException:
+        # Agent construction failed after bridges were started — don't
+        # leak the open transports / spawned subprocesses.
+        await _close_bridges(protocol_bridges)
+        raise
+
 
+async def build_memory_from_config(config: AgentForgeConfig) -> MemoryStore | None:
+    """Resolve + instantiate `modules.memory`. Returns None when absent.
 
-def build_memory_from_config(config: AgentForgeConfig) -> MemoryStore | None:
-    """Resolve + instantiate `modules.memory`. Returns None when absent."""
+    Async because the real memory backends (sqlite/postgres/neo4j/
+    surrealdb) open a connection at construction and expose an async
+    `from_config` factory (bug-022). Falls back to the sync
+    `_instantiate` path for stores that ship a plain/sync constructor.
+    """
     if config.modules.memory is None:
         return None
     cls = _resolve_class("memory", config.modules.memory.driver)
-    instance = _instantiate(cls, config.modules.memory.config)
+    instance = await _ainstantiate_memory(cls, config.modules.memory.config)
     if not isinstance(instance, MemoryStore):
         msg = (
             f"Resolved memory driver {config.modules.memory.driver!r} "
@@ -259,6 +285,83 @@ def build_tools_from_config(config: AgentForgeConfig) -> list[Tool]:
     return tools
 
 
+async def build_protocols_from_config(
+    config: AgentForgeConfig,
+) -> tuple[list[Tool], list[ProtocolBridge]]:
+    """Resolve + start every `modules.protocols` handler (feat-013).
+
+    For each entry: resolve its name under the ``protocols`` resolver
+    category, build the handler via its ``from_config(config)``
+    classmethod, ``await start()`` to open connections and discover
+    tools, then collect the merged tool list. The started bridges are
+    returned so the caller can ``close()`` them on agent teardown.
+
+    Returns an empty ``([], [])`` when no protocols are configured.
+
+    Raises:
+        ModuleError: a protocol isn't registered, lacks a
+            ``from_config`` classmethod, doesn't implement
+            `ProtocolBridge`, or requests server-side ``expose`` (not
+            wired into the runtime yet — see `_reject_unsupported_expose`).
+    """
+    from agentforge_core.contracts.tool import Tool as ToolBase  # noqa: PLC0415
+
+    tools: list[ToolBase] = []
+    bridges: list[ProtocolBridge] = []
+    for entry in config.modules.protocols:
+        _reject_unsupported_expose(entry.name, entry.config)
+        cls = _resolve_class("protocols", entry.name)
+        from_config = getattr(cls, "from_config", None)
+        if not callable(from_config):
+            msg = (
+                f"Resolved protocol {entry.name!r} ({cls.__name__}) has no "
+                f"from_config(config) classmethod."
+            )
+            raise ModuleError(msg)
+        bridge = from_config(entry.config)
+        if not isinstance(bridge, ProtocolBridge):
+            msg = (
+                f"Resolved protocol {entry.name!r} ({cls.__name__}) does not "
+                f"implement ProtocolBridge (needs tools / start / close)."
+            )
+            raise ModuleError(msg)
+        try:
+            await bridge.start()
+        except BaseException:
+            # A later bridge failing must not leak earlier ones.
+            await _close_bridges(bridges)
+            raise
+        bridges.append(bridge)
+        tools.extend(bridge.tools)
+    return tools, bridges
+
+
+def _reject_unsupported_expose(name: str, cfg: dict[str, Any]) -> None:
+    """Fail loud on server-side `expose`, which the runtime can't wire yet.
+
+    Auto-serving an MCP server from inside the agent process would hijack
+    the process's stdio. Consume-only is supported; expose runtime-wiring
+    is a follow-up (tracked alongside enh-001, MCP HTTP server transport).
+    """
+    expose = cfg.get("expose") or {}
+    if expose.get("enabled"):
+        msg = (
+            f"modules.protocols[{name!r}]: server-side `expose` is not wired "
+            "into the agent runtime yet (it would hijack the agent process's "
+            "stdio). Use consume-only config for now; expose runtime-wiring is "
+            "a follow-up (see enh-001)."
+        )
+        raise ModuleError(msg)
+
+
+async def _close_bridges(bridges: list[ProtocolBridge]) -> None:
+    """Close every started bridge, swallowing teardown errors so one bad
+    close doesn't mask the original failure."""
+    for bridge in bridges:
+        with contextlib.suppress(Exception):
+            await bridge.close()
+
+
 def _resolve_llm(config: AgentForgeConfig) -> LLMClient | str | None:
     """Pick the LLM definition out of `config.agent.model` /
     `config.providers["default"]`.
@@ -266,8 +369,12 @@ def _resolve_llm(config: AgentForgeConfig) -> LLMClient | str | None:
     We hand a string back to `Agent.__init__` when the model is a
     plain `"<provider>:<model>"` string — `Agent` already knows how
     to resolve that. When `agent.model` is missing but
-    `providers["default"]` is present, we synthesize the string from
-    the named-provider record.
+    `providers["default"]` is present, the named-provider record is
+    used — and its `config:` block is **passed through to the provider
+    constructor** (enh-004): a plain `type:model` string can only carry
+    the model id, so provider settings (`region`, `aws_profile`,
+    `role_arn`, `timeout_seconds`, …) have to ride the `config` block.
+    Without this they were silently dropped.
     """
     raw = config.agent.model
     if isinstance(raw, str):
@@ -275,7 +382,25 @@ def _resolve_llm(config: AgentForgeConfig) -> LLMClient | str | None:
     default = config.providers.get("default")
     if default is None or default.model is None:
         return None
-    return f"{default.type}:{default.model}"
+    if not default.config:
+        return f"{default.type}:{default.model}"
+    # Construct the provider directly with `model_id` + the `config`
+    # kwargs — the same `cls(model_id=...)` contract `Agent` uses to
+    # resolve a model string (every provider's __init__ accepts
+    # `model_id`), extended with the per-provider settings.
+    cls = _resolve_class("providers", default.type)
+    try:
+        instance = cls(model_id=default.model, **default.config)
+    except TypeError as exc:
+        msg = (
+            f"Provider {default.type!r} ({cls.__name__}) rejected "
+            f"providers.default.config keys {sorted(default.config)}: {exc}"
+        )
+        raise ModuleError(msg) from exc
+    if not isinstance(instance, LLMClient):
+        msg = f"Resolved provider {default.type!r} ({cls.__name__}) does not implement LLMClient."
+        raise ModuleError(msg)
+    return instance
 
 
 def _resolve_class(category: str, name: str) -> type:
@@ -306,6 +431,29 @@ def _instantiate(cls: type, cfg: dict[str, Any]) -> Any:
     return cls(**cfg)
 
 
+async def _ainstantiate_memory(cls: type, cfg: dict[str, Any]) -> Any:
+    """Async-aware construction for memory stores (bug-022).
+
+    Memory backends construct asynchronously (they open a connection)
+    and expose an awaitable `from_config`. Prefer it; if the resolved
+    class only offers a sync constructor (e.g. a test double), fall
+    back to the shared sync `_instantiate`.
+
+    Mirrors `_instantiate`'s keyword-then-positional `from_config`
+    shape so externally-shipped stores using either signature load.
+    """
+    from_config = getattr(cls, "from_config", None)
+    if callable(from_config):
+        try:
+            result = from_config(**cfg)
+        except TypeError:
+            result = from_config(cfg)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+    return cls(**cfg)
+
+
 async def _maybe_init_schema(memory: MemoryStore) -> None:
     init = getattr(memory, "init_schema", None)
     if callable(init):
@@ -317,6 +465,7 @@ __all__ = [
     "build_evaluators_from_config",
     "build_memory_from_config",
     "build_pipeline_from_config",
+    "build_protocols_from_config",
     "build_retriever_from_config",
     "build_tools_from_config",
     "load_and_build",