agentplane-runtime 0.0.1__py3-none-any.whl

agentplane_runtime/serving.py

@@ -0,0 +1,383 @@
+"""Endpoint serving (SPEC §6.5): A2A agents and MCP servers behind the gateway.
+
+The runtime mounts one ASGI sub-app per deployed flow under
+``/a2a/{name}`` (a2a-sdk server, A2A v1.0 wire format) or ``/mcp/{name}``
+(FastMCP, streamable HTTP). Ephemeral draft endpoints live under
+``/a2a/_draft/{name}`` with a TTL and never touch the registry.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from collections.abc import Awaitable, Callable, MutableMapping
+from dataclasses import dataclass
+from typing import Any
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
+from a2a.server.tasks import InMemoryTaskStore, TaskUpdater
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+    Part,
+    Task,
+    TaskState,
+    TaskStatus,
+)
+from fastmcp import FastMCP
+from fastmcp.tools import Tool, ToolResult
+from pydantic import PrivateAttr
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+
+from agentplane_core import (
+    FlowDefinition,
+    JsonObject,
+    StartNode,
+    single_required_string_input,
+)
+from agentplane_runtime.engine import ExecutionContext, FlowRunner, _as_text
+from agentplane_runtime.resources import ResourceService
+from agentplane_runtime.settings import EPHEMERAL_TTL_S, RuntimeSettings
+
+# ASGI protocol types — inherently loose (the ASGI spec is dict-based).
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+def build_agent_card(defn: FlowDefinition, public_url: str) -> AgentCard:
+    """Derive the A2A card from the definition (SPEC §6.5)."""
+    skills = [
+        AgentSkill(
+            id=defn.name,
+            name=defn.display_name or defn.name,
+            description=defn.description or defn.display_name or defn.name,
+            tags=list(defn.tags) or ["flow"],
+        )
+    ]
+    return AgentCard(
+        name=defn.name,
+        description=defn.description,
+        version="1",
+        supported_interfaces=[
+            AgentInterface(url=public_url, protocol_binding="JSONRPC", protocol_version="1.0")
+        ],
+        capabilities=AgentCapabilities(streaming=True),
+        default_input_modes=["text/plain", "application/json"],
+        default_output_modes=["text/plain"],
+        skills=skills,
+    )
+
+
+def bind_message_to_inputs(defn: FlowDefinition, text: str) -> JsonObject:
+    """A2A input binding (SPEC §6.4).
+
+    Message text binds to the single required string property when there is
+    exactly one; otherwise the text must be a JSON object matching the schema.
+    """
+    single = single_required_string_input(defn)
+    if single is not None:
+        return {single: text}
+    try:
+        parsed = json.loads(text)
+    except ValueError as exc:
+        raise ValueError(
+            "flow input schema has multiple properties; send a JSON object message"
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("message must be a JSON object matching the flow input schema")
+    return parsed
+
+
+class FlowAgentExecutor(AgentExecutor):
+    """Runs the flow for each A2A request; streams tokens for stream:true nodes."""
+
+    def __init__(self, runner_factory: Callable[[], FlowRunner], defn: FlowDefinition) -> None:
+        self._runner_factory = runner_factory
+        self._defn = defn
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        task_id = context.task_id or ""
+        context_id = context.context_id or ""
+        if context.current_task is None:
+            # Async workflow: the Task object must be enqueued before updates.
+            await event_queue.enqueue_event(
+                Task(
+                    id=task_id,
+                    context_id=context_id,
+                    status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED),
+                )
+            )
+        updater = TaskUpdater(event_queue, task_id, context_id)
+        await updater.start_work()
+
+        async def stream_chunk(delta: str) -> None:
+            await updater.update_status(
+                TaskState.TASK_STATE_WORKING,
+                message=updater.new_agent_message([Part(text=delta)]),
+            )
+
+        runner = self._runner_factory()
+        try:
+            inputs = bind_message_to_inputs(self._defn, context.get_user_input())
+            result = await runner.execute(inputs, stream=stream_chunk)
+        except ValueError as exc:
+            await updater.failed(updater.new_agent_message([Part(text=str(exc))]))
+            return
+        except Exception as exc:
+            await updater.failed(
+                updater.new_agent_message([Part(text=f"flow execution failed: {exc}")])
+            )
+            return
+        text = _as_text(result) if result is not None else ""
+        await updater.add_artifact([Part(text=text)], name="output")
+        await updater.complete()
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        updater = TaskUpdater(event_queue, context.task_id or "", context.context_id or "")
+        await updater.cancel()
+
+
+def build_a2a_app(
+    defn: FlowDefinition,
+    public_url: str,
+    runner_factory: Callable[[], FlowRunner],
+) -> Starlette:
+    """One Starlette app per A2A-exposed flow: card + JSON-RPC routes."""
+    card = build_agent_card(defn, public_url)
+    handler = DefaultRequestHandler(
+        agent_executor=FlowAgentExecutor(runner_factory, defn),
+        task_store=InMemoryTaskStore(),
+        agent_card=card,
+    )
+    routes: list[Route] = [
+        *create_agent_card_routes(card),
+        *create_jsonrpc_routes(handler, "/"),
+    ]
+    return Starlette(routes=routes)
+
+
+class FlowTool(Tool):
+    """FastMCP tool whose parameters come from ``start.input_schema``."""
+
+    _runner_factory: Callable[[], FlowRunner] = PrivateAttr()
+
+    def bind(self, runner_factory: Callable[[], FlowRunner]) -> FlowTool:
+        self._runner_factory = runner_factory
+        return self
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        runner = self._runner_factory()
+        result = await runner.execute(dict(arguments))
+        return ToolResult(content=_as_text(result) if result is not None else "")
+
+
+def build_mcp_server(defn: FlowDefinition, runner_factory: Callable[[], FlowRunner]) -> FastMCP:
+    """One FastMCP server per MCP-exposed flow, one tool per flow (SPEC §6.5)."""
+    start = next(n for n in defn.nodes if isinstance(n, StartNode))
+    tool_name = defn.expose.tool_name or defn.name.replace("-", "_")
+    server: FastMCP = FastMCP(name=defn.name, instructions=defn.description)
+    tool = FlowTool(
+        name=tool_name,
+        description=defn.expose.tool_description or defn.description,
+        parameters=start.config.input_schema,
+    ).bind(runner_factory)
+    server.add_tool(tool)
+    return server
+
+
+class PathDispatcher:
+    """Dispatches ``/{name}/...`` to per-flow ASGI apps; supports live add/remove."""
+
+    def __init__(self) -> None:
+        self._apps: dict[str, ASGIApp] = {}
+
+    def mount(self, name: str, app: ASGIApp) -> None:
+        self._apps[name] = app
+
+    def unmount(self, name: str) -> None:
+        self._apps.pop(name, None)
+
+    def mounted(self) -> list[str]:
+        return sorted(self._apps)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            return
+        # Starlette convention: `path` is the full request path and `root_path`
+        # the already-consumed prefix; route matching happens on the difference.
+        path: str = scope.get("path", "")
+        root_path: str = scope.get("root_path", "")
+        route_path = path[len(root_path) :] if path.startswith(root_path) else path
+        segments = [s for s in route_path.split("/") if s]
+        name = ""
+        consumed = 0
+        if len(segments) > 1 and segments[0] == "_draft":
+            name = f"_draft/{segments[1]}"
+            consumed = 2
+        elif segments:
+            name = segments[0]
+            consumed = 1
+        app = self._apps.get(name)
+        if app is None:
+            response = PlainTextResponse("no such endpoint", status_code=404)
+            await response(scope, receive, send)
+            return
+        child_scope = dict(scope)
+        child_scope["root_path"] = root_path + "/" + "/".join(segments[:consumed])
+        await app(child_scope, receive, send)
+
+
+class LifespanHost:
+    """Runs an ASGI app's lifespan in a dedicated task.
+
+    anyio cancel scopes must be entered and exited in the same task, so the
+    FastMCP http_app lifespan cannot live in an exit stack that is closed
+    from elsewhere.
+    """
+
+    def __init__(self, app: Starlette) -> None:
+        self._app = app
+        self._started: asyncio.Event = asyncio.Event()
+        self._stop: asyncio.Event = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+
+    async def _run(self) -> None:
+        async with self._app.router.lifespan_context(self._app):
+            self._started.set()
+            await self._stop.wait()
+
+    async def start(self) -> None:
+        self._task = asyncio.create_task(self._run(), name="endpoint-lifespan")
+        await self._started.wait()
+
+    async def stop(self) -> None:
+        if self._task is None:
+            return
+        self._stop.set()
+        await self._task
+        self._task = None
+
+
+@dataclass
+class Endpoint:
+    name: str
+    kind: str  # "a2a" | "mcp"
+    version: int
+    public_url: str
+    lifespan: LifespanHost | None = None
+    expires_at: float | None = None  # ephemeral only
+
+
+class EndpointManager:
+    """Owns the /a2a and /mcp dispatchers and the running endpoints."""
+
+    def __init__(self, resources: ResourceService, settings: RuntimeSettings) -> None:
+        self._resources = resources
+        self._settings = settings
+        self.a2a = PathDispatcher()
+        self.mcp = PathDispatcher()
+        self._endpoints: dict[str, Endpoint] = {}
+
+    def endpoint_for(self, name: str) -> Endpoint | None:
+        return self._endpoints.get(name)
+
+    def _runner_factory(self, defn: FlowDefinition, version: int) -> Callable[[], FlowRunner]:
+        compiled: list[FlowRunner] = []
+
+        def factory() -> FlowRunner:
+            # compile once, reuse the graph; context is shared per endpoint
+            if not compiled:
+                compiled.append(
+                    FlowRunner(
+                        defn,
+                        ExecutionContext(
+                            resources=self._resources,
+                            settings=self._settings,
+                            flow_name=defn.name,
+                            flow_version=version,
+                        ),
+                    )
+                )
+            return compiled[0]
+
+        return factory
+
+    def public_url(self, defn: FlowDefinition, *, ephemeral: bool = False) -> str:
+        base = self._settings.public_base_url.rstrip("/")
+        if ephemeral:
+            return f"{base}/a2a/_draft/{defn.name}"
+        return f"{base}/{defn.expose.kind}/{defn.name}"
+
+    async def start(
+        self, defn: FlowDefinition, version: int, *, ephemeral: bool = False
+    ) -> Endpoint:
+        """(Re)start the endpoint for a definition at a given version."""
+        key = f"_draft/{defn.name}" if ephemeral else defn.name
+        await self.stop(key)
+        public_url = self.public_url(defn, ephemeral=ephemeral)
+        runner_factory = self._runner_factory(defn, version)
+        lifespan: LifespanHost | None = None
+
+        if defn.expose.kind == "mcp" and not ephemeral:
+            server = build_mcp_server(defn, runner_factory)
+            http_app = server.http_app(path="/", stateless_http=True)
+            lifespan = LifespanHost(http_app)
+            await lifespan.start()
+            self.mcp.mount(key, http_app)
+        else:
+            app = build_a2a_app(defn, public_url, runner_factory)
+            self.a2a.mount(key, app)
+
+        endpoint = Endpoint(
+            name=key,
+            kind=defn.expose.kind if not ephemeral else "a2a",
+            version=version,
+            public_url=public_url,
+            lifespan=lifespan,
+            expires_at=time.monotonic() + EPHEMERAL_TTL_S if ephemeral else None,
+        )
+        self._endpoints[key] = endpoint
+        return endpoint
+
+    async def stop(self, name: str) -> None:
+        endpoint = self._endpoints.pop(name, None)
+        if endpoint is None:
+            return
+        if endpoint.kind == "mcp":
+            self.mcp.unmount(name)
+        else:
+            self.a2a.unmount(name)
+        if endpoint.lifespan is not None:
+            await endpoint.lifespan.stop()
+
+    async def stop_all(self) -> None:
+        for name in list(self._endpoints):
+            await self.stop(name)
+
+    async def reap_expired(self) -> None:
+        """Drop ephemeral endpoints past their TTL."""
+        now = time.monotonic()
+        for name, endpoint in list(self._endpoints.items()):
+            if endpoint.expires_at is not None and endpoint.expires_at < now:
+                await self.stop(name)
+
+
+__all__ = [
+    "EndpointManager",
+    "FlowAgentExecutor",
+    "PathDispatcher",
+    "bind_message_to_inputs",
+    "build_a2a_app",
+    "build_agent_card",
+    "build_mcp_server",
+]

agentplane_runtime/settings.py

@@ -0,0 +1,31 @@
+"""Runtime configuration (SPEC §7.2), env prefix ``AGENTPLANE_RUNTIME_``."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+RUNTIME_VERSION = "0.0.1"
+
+EPHEMERAL_TTL_S = 30 * 60  # SPEC §6.2: draft endpoints live 30 minutes
+
+
+class RuntimeSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AGENTPLANE_RUNTIME_", extra="ignore")
+
+    db_url: str = "sqlite+aiosqlite:///runtime.db"
+    public_base_url: str = ""  # required to serve; validated on app start
+    registry_url: str = ""  # required to self-register; empty disables registration
+    registry_token: str = ""
+    secret_key: str = ""  # Fernet key; required for resources with secrets
+    llm_base_url: str = ""  # gateway's OpenAI-compatible endpoint (resource default)
+    auth_mode: Literal["none", "oidc"] = "none"
+    oidc_issuer: str = ""
+    oidc_audience: str = ""
+    roles_claim: str = "realm_access.roles"
+    admin_role: str = "admin"
+    http_timeout_s: float = 60.0
+
+
+__all__ = ["EPHEMERAL_TTL_S", "RUNTIME_VERSION", "RuntimeSettings"]

agentplane_runtime/tracing.py

@@ -0,0 +1,52 @@
+"""OpenTelemetry wiring — OTLP endpoint is configuration, never a vendor SDK.
+
+Uses the standard ``OTEL_EXPORTER_OTLP_ENDPOINT`` variable; without it the
+no-op tracer provider stays active and nothing is exported.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Awaitable, Callable
+
+from fastapi import FastAPI, Request, Response
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Status, StatusCode
+
+
+def setup_tracing(app: FastAPI, *, service_name: str) -> None:
+    """Install an OTLP exporter (when configured) and a request span middleware."""
+    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+    if endpoint:
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # noqa: PLC0415
+            OTLPSpanExporter,
+        )
+
+        provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+        trace.set_tracer_provider(provider)
+
+    tracer = trace.get_tracer(service_name)
+
+    @app.middleware("http")
+    async def _trace_requests(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        with tracer.start_as_current_span(
+            f"{request.method} {request.url.path}",
+            attributes={
+                "http.request.method": request.method,
+                "url.path": request.url.path,
+            },
+        ) as span:
+            response = await call_next(request)
+            span.set_attribute("http.response.status_code", response.status_code)
+            if response.status_code >= 500:  # noqa: PLR2004
+                span.set_status(Status(StatusCode.ERROR))
+            return response
+
+
+__all__ = ["setup_tracing"]

agentplane_runtime/validation.py

@@ -0,0 +1,91 @@
+"""Stateful validation (SPEC §3.7): core checks + E020/E021/E022/W001.
+
+The runtime's answer (``POST /definitions/validate``) is authoritative; it
+runs ``agentplane_core.validation.validate_structure`` first — literally the
+same code the builder uses locally — and adds the checks that need runtime
+state (resources, dimensions, deprecations).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from agentplane_core import (
+    DEPRECATED_NODE_VERSIONS,
+    FlowDefinition,
+    LlmCallNode,
+    McpToolNode,
+    RetrievalNode,
+    ValidationIssue,
+    ValidationResult,
+    VectorDBResource,
+    validate_structure,
+)
+from agentplane_core.resources import VECTOR_DB_KINDS
+from agentplane_runtime.resources import ResourceNotFoundError, ResourceService
+
+_EXPECTED_KINDS = {
+    "llm_call": frozenset({"model_provider"}),
+    "retrieval": VECTOR_DB_KINDS,
+    "mcp_tool": frozenset({"mcp_server"}),
+}
+
+
+def _issue(code: str, severity: str, path: str, message: str) -> ValidationIssue:
+    return ValidationIssue.model_validate(
+        {"code": code, "severity": severity, "path": path, "message": message}
+    )
+
+
+async def validate_full(
+    defn: FlowDefinition | Mapping[str, object], resources: ResourceService
+) -> ValidationResult:
+    """Structural checks (core) + resource/dimension/deprecation checks."""
+    issues = list(validate_structure(defn))
+    if any(i.severity == "error" for i in issues):
+        return ValidationResult.from_issues(issues)
+
+    parsed = defn if isinstance(defn, FlowDefinition) else FlowDefinition.model_validate(dict(defn))
+
+    for node in parsed.nodes:
+        if (node.type, node.version) in DEPRECATED_NODE_VERSIONS:
+            issues.append(
+                _issue(
+                    "W001",
+                    "warning",
+                    f"nodes/{node.id}/version",
+                    f"node version {node.version} of {node.type!r} is deprecated",
+                )
+            )
+        if not isinstance(node, LlmCallNode | RetrievalNode | McpToolNode):
+            continue
+        resource_name = node.config.resource
+        if resource_name is None:  # mcp_tool with direct url
+            continue
+        path = f"nodes/{node.id}/config/resource"
+        try:
+            resource = await resources.get_raw(resource_name)
+        except ResourceNotFoundError:
+            issues.append(_issue("E020", "error", path, f"unknown resource {resource_name!r}"))
+            continue
+        expected = _EXPECTED_KINDS[node.type]
+        if resource.kind not in expected:
+            issues.append(
+                _issue(
+                    "E021",
+                    "error",
+                    path,
+                    f"resource {resource_name!r} has kind {resource.kind!r}; "
+                    f"expected one of {sorted(expected)}",
+                )
+            )
+            continue
+        if isinstance(node, RetrievalNode) and isinstance(resource, VectorDBResource):
+            e022 = await resources.check_collection_dimension(resource, node.config.collection)
+            if e022 is not None:
+                issues.append(e022)
+
+    return ValidationResult.from_issues(issues)
+
+
+__all__ = ["validate_full"]