agno-agent-builder 0.1.1__tar.gz

agno_agent_builder-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env

agno_agent_builder-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

agno_agent_builder-0.1.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1](https://github.com/Zetesis-Labs/PayloadAgents/compare/agno-agent-builder-v0.1.0...agno-agent-builder-v0.1.1) (2026-04-30)
+
+
+### Features
+
+* uv workspace backend + MCP token taxonomies + release-please ([#44](https://github.com/Zetesis-Labs/PayloadAgents/issues/44)) ([5ffdff5](https://github.com/Zetesis-Labs/PayloadAgents/commit/5ffdff5b574026a6a16be52166c1be350c1ad326))

agno_agent_builder-0.1.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: agno-agent-builder
+Version: 0.1.1
+Summary: Parametrizable Agno-based agent runtime — FastAPI factory with pluggable agent sources, multi-tenant headers, and LISTEN/NOTIFY hot reload.
+Project-URL: Homepage, https://github.com/Zetesis-Labs/PayloadAgents
+Project-URL: Repository, https://github.com/Zetesis-Labs/PayloadAgents
+Project-URL: Issues, https://github.com/Zetesis-Labs/PayloadAgents/issues
+Author: Zetesis Labs
+License: MIT
+Keywords: agent,agno,fastapi,llm,mcp,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: agno[anthropic,mcp,openai,os,postgres]>=2.5.16
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pydantic>=2.9
+Requires-Dist: structlog>=24.1
+Requires-Dist: uvicorn[standard]>=0.34
+Description-Content-Type: text/markdown
+
+# agno-agent-builder
+
+Parametrizable Agno runtime as a library. Build a fully configured FastAPI app
+for chat with hot-reloadable agents fetched from any source you plug in.
+
+## Quick start
+
+```python
+from agno_agent_builder import create_app, RuntimeConfig, PayloadAgentSource
+
+app = create_app(
+    RuntimeConfig(
+        app_name="my-runtime",
+        agent_source=PayloadAgentSource(
+            base_url="http://payload:3000",
+            internal_secret="...",
+        ),
+        mcp_url="http://mcp:3001/mcp",
+        database_url="postgresql://user:pass@host:5432/db",
+        internal_secret="...",
+    )
+)
+```
+
+## Public API
+
+| Symbol | Purpose |
+|---|---|
+| `create_app(config)` | Returns a configured FastAPI app |
+| `RuntimeConfig` | Pydantic model — required + optional knobs |
+| `AgentSource` | Protocol — implement `async fetch_agents() -> list[AgentConfig]` |
+| `AgentConfig` | Normalized per-agent record (CMS-agnostic) |
+| `PayloadAgentSource` | Default source for Payload CMS |
+| `build_agent`, `build_model`, `build_mcp_tools` | Lower-level builders for advanced wiring |
+| `compose_instructions`, `DEFAULT_TOOL_PROTOCOL`, `DEFAULT_OUTPUT_FORMAT` | Override-friendly prompt building blocks |
+
+## What you get
+
+- AgentOS REST surface (`/agents`, `/sessions`, `/metrics`, …)
+- `POST /agents/{slug}/runs` SSE chat
+- `/health`, `/ready` Kubernetes probes
+- `POST /internal/agents/reload` admin endpoint
+- Postgres `LISTEN/NOTIFY` hot reload + 5-min belt-and-braces resync
+- ASGI middlewares: `X-Request-ID`, `X-Internal-Secret` auth, `X-Tenant-Id` → `request.state.metadata`
+
+## Reference consumer
+
+The default consumer that ships in this repo lives in
+[`../agno-agent`](../agno-agent) — it wraps `create_app` with env-driven
+settings and is what runs in the `agno-agent` devcontainer service. ZP and
+nexus install this lib from PyPI and write their own thin consumer.

agno_agent_builder-0.1.1/README.md

@@ -0,0 +1,51 @@
+# agno-agent-builder
+
+Parametrizable Agno runtime as a library. Build a fully configured FastAPI app
+for chat with hot-reloadable agents fetched from any source you plug in.
+
+## Quick start
+
+```python
+from agno_agent_builder import create_app, RuntimeConfig, PayloadAgentSource
+
+app = create_app(
+    RuntimeConfig(
+        app_name="my-runtime",
+        agent_source=PayloadAgentSource(
+            base_url="http://payload:3000",
+            internal_secret="...",
+        ),
+        mcp_url="http://mcp:3001/mcp",
+        database_url="postgresql://user:pass@host:5432/db",
+        internal_secret="...",
+    )
+)
+```
+
+## Public API
+
+| Symbol | Purpose |
+|---|---|
+| `create_app(config)` | Returns a configured FastAPI app |
+| `RuntimeConfig` | Pydantic model — required + optional knobs |
+| `AgentSource` | Protocol — implement `async fetch_agents() -> list[AgentConfig]` |
+| `AgentConfig` | Normalized per-agent record (CMS-agnostic) |
+| `PayloadAgentSource` | Default source for Payload CMS |
+| `build_agent`, `build_model`, `build_mcp_tools` | Lower-level builders for advanced wiring |
+| `compose_instructions`, `DEFAULT_TOOL_PROTOCOL`, `DEFAULT_OUTPUT_FORMAT` | Override-friendly prompt building blocks |
+
+## What you get
+
+- AgentOS REST surface (`/agents`, `/sessions`, `/metrics`, …)
+- `POST /agents/{slug}/runs` SSE chat
+- `/health`, `/ready` Kubernetes probes
+- `POST /internal/agents/reload` admin endpoint
+- Postgres `LISTEN/NOTIFY` hot reload + 5-min belt-and-braces resync
+- ASGI middlewares: `X-Request-ID`, `X-Internal-Secret` auth, `X-Tenant-Id` → `request.state.metadata`
+
+## Reference consumer
+
+The default consumer that ships in this repo lives in
+[`../agno-agent`](../agno-agent) — it wraps `create_app` with env-driven
+settings and is what runs in the `agno-agent` devcontainer service. ZP and
+nexus install this lib from PyPI and write their own thin consumer.

agno_agent_builder-0.1.1/agno_agent_builder/__init__.py

@@ -0,0 +1,73 @@
+"""agno-agent — parametrizable Agno runtime as a library.
+
+Build a fully configured FastAPI app from a `RuntimeConfig`:
+
+    from agno_agent_builder import create_app, RuntimeConfig, PayloadAgentSource
+
+    app = create_app(
+        RuntimeConfig(
+            app_name="my-runtime",
+            agent_source=PayloadAgentSource(
+                base_url="http://payload:3000",
+                internal_secret=secret,
+            ),
+            mcp_url="http://mcp:3001/mcp",
+            database_url="postgresql://...",
+            internal_secret=secret,
+        )
+    )
+"""
+
+from __future__ import annotations
+
+from agno_agent_builder.app import create_app
+from agno_agent_builder.builder import build_agent, build_mcp_tools, build_model
+from agno_agent_builder.config import (
+    DEFAULT_BOOT_BACKOFF_BASE,
+    DEFAULT_BOOT_BACKOFF_MAX,
+    DEFAULT_BOOT_MAX_RETRIES,
+    DEFAULT_PUBLIC_PATHS,
+    DEFAULT_RELOAD_CHANNEL,
+    DEFAULT_RESYNC_INTERVAL_S,
+    RuntimeConfig,
+)
+from agno_agent_builder.exceptions import (
+    AgentConfigError,
+    AgentRuntimeError,
+    AuthenticationError,
+    InvalidModelError,
+    MissingApiKeyError,
+    UnsupportedProviderError,
+)
+from agno_agent_builder.instructions import (
+    DEFAULT_OUTPUT_FORMAT,
+    DEFAULT_TOOL_PROTOCOL,
+    compose_instructions,
+)
+from agno_agent_builder.sources import AgentConfig, AgentSource, PayloadAgentSource
+
+__all__ = [
+    "DEFAULT_BOOT_BACKOFF_BASE",
+    "DEFAULT_BOOT_BACKOFF_MAX",
+    "DEFAULT_BOOT_MAX_RETRIES",
+    "DEFAULT_OUTPUT_FORMAT",
+    "DEFAULT_PUBLIC_PATHS",
+    "DEFAULT_RELOAD_CHANNEL",
+    "DEFAULT_RESYNC_INTERVAL_S",
+    "DEFAULT_TOOL_PROTOCOL",
+    "AgentConfig",
+    "AgentConfigError",
+    "AgentRuntimeError",
+    "AgentSource",
+    "AuthenticationError",
+    "InvalidModelError",
+    "MissingApiKeyError",
+    "PayloadAgentSource",
+    "RuntimeConfig",
+    "UnsupportedProviderError",
+    "build_agent",
+    "build_mcp_tools",
+    "build_model",
+    "compose_instructions",
+    "create_app",
+]

agno_agent_builder-0.1.1/agno_agent_builder/app.py

@@ -0,0 +1,166 @@
+"""`create_app(config)` factory — wires AgentOS, registry, listener, lifespan."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hmac
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+from agno.agent import Agent, AgentFactory
+from agno.agent.protocol import AgentProtocol
+from agno.agent.remote import RemoteAgent
+from agno.os import AgentOS
+from fastapi import APIRouter, Depends, FastAPI, Header
+
+from agno_agent_builder.config import RuntimeConfig
+from agno_agent_builder.db import EngineHolder
+from agno_agent_builder.dependencies import get_registry
+from agno_agent_builder.exceptions import (
+    AgentRuntimeError,
+    AuthenticationError,
+    agno_agent_builder_exception_handler,
+)
+from agno_agent_builder.health import router as health_router
+from agno_agent_builder.logging import configure_logging, get_logger
+from agno_agent_builder.middleware import (
+    InternalAuthMiddleware,
+    RequestIdMiddleware,
+    SessionMetadataMiddleware,
+)
+from agno_agent_builder.registry import AgentRegistry
+from agno_agent_builder.reload_listener import run_reload_listener
+from agno_agent_builder.schemas import ErrorResponse, ReloadResponse
+
+_AgentList = list[Agent | RemoteAgent | AgentProtocol | AgentFactory]
+
+
+def _agents_as_union(agents: list[Agent]) -> _AgentList:
+    return cast(_AgentList, agents)
+
+
+def create_app(config: RuntimeConfig) -> FastAPI:
+    """Build a fully configured FastAPI app for the Agno runtime."""
+    configure_logging(config.log_level)
+    logger = get_logger(config.app_name)
+
+    secret = config.internal_secret.get_secret_value()
+    registry = AgentRegistry(
+        source=config.agent_source,
+        database_url=config.database_url,
+        database_schema=config.database_schema,
+        mcp_url=config.mcp_url,
+        tool_protocol=config.tool_protocol,
+        output_format=config.output_format,
+    )
+    engine_holder = EngineHolder(config.database_url)
+    reload_lock = asyncio.Lock()
+
+    async def reload_registry(_payload: str | None = None) -> None:
+        async with reload_lock:
+            await registry.reload()
+            agent_os.agents = _agents_as_union(registry.all())
+        logger.info(
+            "Registry reloaded via notify", count=len(registry.all()), slugs=registry.slugs()
+        )
+
+    async def periodic_resync() -> None:
+        while True:
+            await asyncio.sleep(config.resync_interval_s)
+            try:
+                await reload_registry()
+            except Exception:
+                logger.exception("Periodic resync failed, will retry on next tick")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.registry = registry
+        app.state.engine_holder = engine_holder
+
+        for attempt in range(1, config.boot_max_retries + 1):
+            try:
+                await registry.load_all()
+                agent_os.agents = _agents_as_union(registry.all())
+                logger.info("AgentOS initialised", agent_count=len(registry.all()))
+                break
+            except Exception:
+                delay = min(config.boot_backoff_base**attempt, config.boot_backoff_max)
+                if attempt < config.boot_max_retries:
+                    logger.warning(
+                        "Bootstrap failed, retrying",
+                        attempt=attempt,
+                        max_retries=config.boot_max_retries,
+                        delay_s=delay,
+                        exc_info=True,
+                    )
+                    await asyncio.sleep(delay)
+                else:
+                    logger.critical(
+                        "Failed to bootstrap after max retries — service will only expose health endpoints",
+                        max_retries=config.boot_max_retries,
+                        exc_info=True,
+                    )
+
+        listener_task = asyncio.create_task(
+            run_reload_listener(
+                reload_registry,
+                database_url=config.database_url,
+                channel=config.reload_channel,
+            )
+        )
+        resync_task = asyncio.create_task(periodic_resync())
+        yield
+        for task in (listener_task, resync_task):
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+        logger.info("Shutting down — disposing shared DB engine")
+        await engine_holder.dispose()
+
+    agent_os_kwargs: dict[str, Any] = {
+        "telemetry": False,
+        "authorization": False,
+        "auto_provision_dbs": True,
+        **config.agent_os_kwargs,
+    }
+    agent_os = AgentOS(
+        name=config.app_name,
+        db=registry.db,
+        agents=[],
+        lifespan=lifespan,
+        **agent_os_kwargs,
+    )
+
+    app: FastAPI = agent_os.get_app()
+    app.add_middleware(SessionMetadataMiddleware)
+    app.add_middleware(RequestIdMiddleware)
+    app.add_middleware(InternalAuthMiddleware, secret=secret, public_paths=config.public_paths)
+    app.add_exception_handler(AgentRuntimeError, agno_agent_builder_exception_handler)
+    app.include_router(health_router)
+
+    internal_router = APIRouter(prefix="/internal", tags=["internal"])
+
+    @internal_router.post(
+        "/agents/reload",
+        response_model=ReloadResponse,
+        responses={401: {"model": ErrorResponse}},
+    )
+    async def reload_agents(
+        reg: AgentRegistry = Depends(get_registry),
+        x_internal_secret: str | None = Header(default=None, alias="X-Internal-Secret"),
+    ) -> ReloadResponse:
+        if not hmac.compare_digest(x_internal_secret or "", secret):
+            raise AuthenticationError()
+        async with reload_lock:
+            await reg.reload()
+            agent_os.agents = _agents_as_union(reg.all())
+        count = len(reg.all())
+        logger.info("Agents reloaded", count=count, slugs=reg.slugs())
+        return ReloadResponse(count=count, slugs=reg.slugs())
+
+    app.include_router(internal_router)
+
+    return app

agno_agent_builder-0.1.1/agno_agent_builder/builder.py

@@ -0,0 +1,78 @@
+"""Agent construction — maps `AgentConfig` records into Agno `Agent` instances."""
+
+from __future__ import annotations
+
+from agno.agent import Agent
+from agno.db.postgres import PostgresDb
+from agno.models.anthropic import Claude
+from agno.models.base import Model
+from agno.models.openai import OpenAIChat, OpenAIResponses
+from agno.tools.mcp import MCPTools
+from agno.tools.mcp.params import StreamableHTTPClientParams
+
+from agno_agent_builder.exceptions import InvalidModelError, UnsupportedProviderError
+from agno_agent_builder.instructions import compose_instructions
+from agno_agent_builder.sources.types import AgentConfig
+
+_OPENAI_RESPONSES_PREFIXES = ("o1", "o3", "o4", "gpt-4.1", "gpt-5")
+_NATIVE_REASONER_PREFIXES = ("o1", "o3", "o4")
+
+
+def build_agent(
+    cfg: AgentConfig,
+    *,
+    db: PostgresDb,
+    mcp_url: str,
+    tool_protocol: str | None = None,
+    output_format: str | None = None,
+) -> Agent:
+    """Construct an Agno Agent from a normalized AgentConfig."""
+    provider, _, model_id = cfg.llm_model.partition("/")
+    if not model_id:
+        raise InvalidModelError(slug=cfg.slug, llm_model=cfg.llm_model)
+
+    is_native_reasoner = any(model_id.startswith(p) for p in _NATIVE_REASONER_PREFIXES)
+
+    return Agent(
+        name=cfg.name,
+        id=cfg.slug,
+        model=build_model(provider, model_id, cfg.api_key.get_secret_value()),
+        instructions=compose_instructions(
+            cfg, tool_protocol=tool_protocol, output_format=output_format
+        ),
+        db=db,
+        tools=[build_mcp_tools(mcp_url, cfg.tenant_slug, cfg.taxonomy_slugs)],
+        add_history_to_context=True,
+        num_history_runs=5,
+        reasoning=not is_native_reasoner,
+        tool_call_limit=cfg.tool_call_limit,
+        telemetry=False,
+    )
+
+
+def build_model(provider: str, model_id: str, api_key: str) -> Model:
+    """Map a provider/model-id tuple to an Agno model instance."""
+    if provider == "anthropic":
+        return Claude(id=model_id, api_key=api_key)
+    if provider == "openai":
+        if any(model_id.startswith(p) for p in _OPENAI_RESPONSES_PREFIXES):
+            return OpenAIResponses(id=model_id, api_key=api_key)
+        return OpenAIChat(id=model_id, api_key=api_key)
+    raise UnsupportedProviderError(provider=provider)
+
+
+def build_mcp_tools(
+    mcp_url: str,
+    tenant_slug: str | None = None,
+    taxonomy_slugs: list[str] | None = None,
+) -> MCPTools:
+    """Build an MCPTools instance with tenant/taxonomy headers."""
+    headers: dict[str, str] = {}
+    if tenant_slug:
+        headers["x-tenant-slug"] = tenant_slug
+    if taxonomy_slugs:
+        headers["x-taxonomy-slugs"] = ",".join(taxonomy_slugs)
+    if headers:
+        params = StreamableHTTPClientParams(url=mcp_url, headers=headers)
+        return MCPTools(server_params=params, transport="streamable-http")
+    return MCPTools(url=mcp_url, transport="streamable-http")

agno_agent_builder-0.1.1/agno_agent_builder/config.py

@@ -0,0 +1,44 @@
+"""Runtime configuration accepted by `create_app`.
+
+Pure data model — no env loading inside the library. Consumers build a
+`RuntimeConfig` from their own settings layer (typically pydantic-settings)
+and pass it to `create_app`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from agno_agent_builder.sources.base import AgentSource
+
+DEFAULT_PUBLIC_PATHS: tuple[str, ...] = ("/health", "/ready", "/docs", "/openapi.json")
+DEFAULT_RELOAD_CHANNEL = "agent_reload"
+DEFAULT_RESYNC_INTERVAL_S = 300.0
+DEFAULT_BOOT_MAX_RETRIES = 10
+DEFAULT_BOOT_BACKOFF_BASE = 2.0
+DEFAULT_BOOT_BACKOFF_MAX = 30.0
+
+
+class RuntimeConfig(BaseModel):
+    """Top-level configuration for `create_app`."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    app_name: str
+    agent_source: AgentSource
+    mcp_url: str
+    database_url: str
+    internal_secret: SecretStr
+    database_schema: str = "agno"
+    log_level: str = "INFO"
+    reload_channel: str = DEFAULT_RELOAD_CHANNEL
+    resync_interval_s: float = DEFAULT_RESYNC_INTERVAL_S
+    boot_max_retries: int = DEFAULT_BOOT_MAX_RETRIES
+    boot_backoff_base: float = DEFAULT_BOOT_BACKOFF_BASE
+    boot_backoff_max: float = DEFAULT_BOOT_BACKOFF_MAX
+    public_paths: tuple[str, ...] = DEFAULT_PUBLIC_PATHS
+    tool_protocol: str | None = None
+    output_format: str | None = None
+    agent_os_kwargs: dict[str, Any] = Field(default_factory=dict)

agno_agent_builder-0.1.1/agno_agent_builder/db.py

@@ -0,0 +1,61 @@
+"""Async SQLAlchemy engine helper for health checks.
+
+Stateless — `EngineHolder` is instantiated per-app inside `create_app` so
+multiple runtime instances (tests, multi-tenancy) don't share a cached
+engine. `normalize_pg_url` is exported because `reload_listener` and
+session storage need the same scheme normalization.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from agno_agent_builder.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def normalize_pg_url(url: str) -> str:
+    """Force psycopg v3 driver (installed via agno[postgres])."""
+    for prefix in ("postgresql://", "postgres://"):
+        if url.startswith(prefix):
+            return "postgresql+psycopg://" + url[len(prefix) :]
+    return url
+
+
+class EngineHolder:
+    """Lazy async engine cache, scoped to one runtime instance."""
+
+    def __init__(self, database_url: str) -> None:
+        self._database_url = database_url
+        self._engine: AsyncEngine | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self) -> AsyncEngine:
+        if self._engine is not None:
+            return self._engine
+        async with self._lock:
+            if self._engine is not None:
+                return self._engine
+            sync_url = normalize_pg_url(self._database_url)
+            async_url = sync_url.replace("postgresql+psycopg://", "postgresql+psycopg_async://")
+            self._engine = create_async_engine(async_url, pool_size=5, pool_pre_ping=True)
+            return self._engine
+
+    async def check(self) -> bool:
+        try:
+            engine = await self.get()
+            async with engine.connect() as conn:
+                await conn.execute(text("SELECT 1"))
+            return True
+        except Exception:
+            logger.warning("DB health check failed", exc_info=True)
+            return False
+
+    async def dispose(self) -> None:
+        if self._engine is not None:
+            await self._engine.dispose()
+            self._engine = None

agno_agent_builder-0.1.1/agno_agent_builder/dependencies.py

@@ -0,0 +1,19 @@
+"""FastAPI dependencies for dependency injection."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import Request
+
+if TYPE_CHECKING:
+    from agno_agent_builder.db import EngineHolder
+    from agno_agent_builder.registry import AgentRegistry
+
+
+async def get_registry(request: Request) -> AgentRegistry:
+    return request.app.state.registry  # type: ignore[no-any-return]
+
+
+async def get_engine_holder(request: Request) -> EngineHolder:
+    return request.app.state.engine_holder  # type: ignore[no-any-return]