agentlings 0.2.0__py3-none-any.whl

agentlings/protocol/agent_card.py

@@ -0,0 +1,83 @@
+"""Agent Card generation from configuration."""
+
+from __future__ import annotations
+
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+    APIKeySecurityScheme,
+    SecurityRequirement,
+    SecurityScheme,
+    StringList,
+)
+from a2a.utils.constants import PROTOCOL_VERSION_1_0, TransportProtocol
+
+from agentlings.config import AgentConfig
+
+
+def generate_agent_card(config: AgentConfig) -> AgentCard:
+    """Generate an A2A Agent Card from the agent's configuration.
+
+    Skills are taken from the YAML definition if provided, otherwise a
+    single default skill is generated from the agent's name and description.
+
+    Args:
+        config: The agent configuration.
+
+    Returns:
+        A fully populated ``AgentCard`` instance.
+    """
+    if config.agent_external_url:
+        url = config.agent_external_url.rstrip("/") + "/a2a"
+    else:
+        url = f"http://{config.agent_host}:{config.agent_port}/a2a"
+
+    if config.skills:
+        skills = [
+            AgentSkill(
+                id=s.id,
+                name=s.name,
+                description=s.description,
+                tags=list(s.tags),
+            )
+            for s in config.skills
+        ]
+    else:
+        skills = [
+            AgentSkill(
+                id=config.agent_name,
+                name=config.agent_name,
+                description=config.agent_description,
+                tags=[],
+            )
+        ]
+
+    return AgentCard(
+        name=config.agent_name,
+        description=config.agent_description,
+        version="0.1.0",
+        supported_interfaces=[
+            AgentInterface(
+                url=url,
+                protocol_binding=TransportProtocol.JSONRPC,
+                protocol_version=PROTOCOL_VERSION_1_0,
+            ),
+        ],
+        skills=skills,
+        capabilities=AgentCapabilities(streaming=False, push_notifications=False),
+        default_input_modes=["text"],
+        default_output_modes=["text"],
+        security_schemes={
+            "apiKey": SecurityScheme(
+                api_key_security_scheme=APIKeySecurityScheme(
+                    location="header",
+                    name="X-API-Key",
+                )
+            )
+        },
+        security_requirements=[
+            SecurityRequirement(schemes={"apiKey": StringList(list=[])})
+        ],
+    )

agentlings/protocol/mcp.py

@@ -0,0 +1,232 @@
+"""MCP protocol server exposing the agentling as a single task-aware tool.
+
+The tool has four input fields:
+
+- ``contextId`` (optional) — which conversation to append to or continue.
+- ``message`` (optional) — a new request to the agent.
+- ``taskId`` (optional) — an existing task to poll.
+- ``waitSeconds`` (optional) — when polling, how long to block for completion.
+
+``message`` and ``taskId`` are mutually exclusive. Sending ``message`` starts a
+task; sending ``taskId`` polls an existing one. In either case the response is
+a ``CallToolResult`` whose ``structuredContent`` tells the caller whether the
+task completed (and the final response) or is still working (with the taskId
+to poll later).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from a2a.types import AgentCard
+from mcp.server.lowlevel import Server
+from mcp.types import TextContent, Tool
+
+from agentlings.config import AgentConfig
+from agentlings.core.loop import MessageLoop
+from agentlings.core.task import (
+    ContextBusyError,
+    InvalidTaskInputError,
+    TaskContextMismatchError,
+    TaskNotFoundError,
+    TaskState,
+    TaskStatus,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def create_mcp_server(
+    loop: MessageLoop,
+    agent_card: AgentCard,
+    config: AgentConfig,
+) -> Server:
+    """Create an MCP server with a single task-aware tool.
+
+    Args:
+        loop: The message loop exposing the shared task engine.
+        agent_card: The agent card whose name and description define the tool.
+        config: Agent configuration (for the await timeout cap).
+
+    Returns:
+        A configured MCP ``Server`` instance.
+    """
+    server = Server(agent_card.name)
+    engine = loop.engine
+    await_seconds = float(getattr(config, "agent_task_await_seconds", 60))
+
+    tool = Tool(
+        name=agent_card.name,
+        description=(
+            f"{agent_card.description}\n\n"
+            "Exactly one of `message` or `taskId` must be provided:\n"
+            "- `message`: start a new task (natural-language request).\n"
+            "- `taskId`: poll an existing task returned by a prior call "
+            "whose status was `working`.\n\n"
+            "The response's `structuredContent.status` is either `completed` "
+            "(final response in `message`) or `working` (retry with `taskId`). "
+            "`waitSeconds` applies only to polls and is capped at "
+            f"{int(await_seconds)} seconds."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "contextId": {
+                    "type": "string",
+                    "description": (
+                        "Context ID from a previous response. Optional. Include "
+                        "to continue an existing conversation."
+                    ),
+                },
+                "message": {
+                    "type": "string",
+                    "description": (
+                        "Natural language request to the agent. Mutually "
+                        "exclusive with `taskId`."
+                    ),
+                },
+                "taskId": {
+                    "type": "string",
+                    "description": (
+                        "Task ID returned by a prior call that yielded a working "
+                        "status. Mutually exclusive with `message`."
+                    ),
+                },
+                "waitSeconds": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": (
+                        "Maximum seconds to block on a poll, capped server-side. "
+                        "Ignored when `message` is provided."
+                    ),
+                },
+            },
+            "additionalProperties": False,
+        },
+    )
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [tool]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        if name != agent_card.name:
+            return _error_payload("unknown_tool", f"Unknown tool: {name}")
+
+        message = arguments.get("message")
+        task_id = arguments.get("taskId")
+        context_id = arguments.get("contextId")
+        wait_seconds = arguments.get("waitSeconds", 0.0)
+
+        if (message is None or message == "") and not task_id:
+            return _error_payload(
+                "invalid_input",
+                "Either `message` or `taskId` must be provided.",
+            )
+        if message and task_id:
+            return _error_payload(
+                "invalid_input",
+                "`message` and `taskId` are mutually exclusive.",
+            )
+
+        try:
+            if task_id:
+                state = await engine.poll(
+                    task_id=task_id,
+                    context_id=context_id,
+                    wait_seconds=wait_seconds,
+                    cap_seconds=await_seconds,
+                )
+            else:
+                assert message is not None
+                state = await engine.spawn(
+                    message=message,
+                    context_id=context_id,
+                    via="mcp",
+                    await_seconds=await_seconds,
+                )
+        except ContextBusyError as e:
+            return _error_payload(
+                "context_busy",
+                str(e),
+                active_task_id=e.active_task_id,
+                context_id=e.context_id,
+            )
+        except TaskNotFoundError as e:
+            return _error_payload("task_not_found", str(e), task_id=e.task_id)
+        except TaskContextMismatchError as e:
+            return _error_payload(
+                "task_context_mismatch",
+                str(e),
+                task_id=e.task_id,
+            )
+        except InvalidTaskInputError as e:
+            return _error_payload("invalid_input", str(e))
+
+        return _format_state(state, await_seconds)
+
+    return server
+
+
+def _format_state(state: TaskState, await_seconds: float) -> list[TextContent]:
+    """Turn a ``TaskState`` into an MCP ``CallToolResult`` payload."""
+    structured: dict[str, Any] = {
+        "taskId": state.task_id,
+        "contextId": state.context_id,
+        "status": state.status.value,
+    }
+    if state.status == TaskStatus.COMPLETED:
+        response_text = _extract_text(state.content)
+        structured["message"] = response_text
+        envelope = {
+            "contextId": state.context_id,
+            "taskId": state.task_id,
+            "message": response_text,
+            "status": state.status.value,
+        }
+        return [TextContent(
+            type="text",
+            text=json.dumps(envelope),
+        )]
+
+    if state.status == TaskStatus.WORKING:
+        structured["pollAfterMs"] = 10_000
+        human = (
+            f"Task {state.task_id} still running. "
+            f"Call again with taskId={state.task_id} to poll "
+            f"(waitSeconds up to {int(await_seconds)})."
+        )
+        envelope = {
+            "contextId": state.context_id,
+            "taskId": state.task_id,
+            "status": state.status.value,
+            "message": human,
+            "pollAfterMs": 10_000,
+        }
+        return [TextContent(type="text", text=json.dumps(envelope))]
+
+    # Failed or cancelled — return an error-shaped payload.
+    envelope = {
+        "contextId": state.context_id,
+        "taskId": state.task_id,
+        "status": state.status.value,
+        "error": state.error or state.status.value,
+    }
+    return [TextContent(type="text", text=json.dumps(envelope))]
+
+
+def _error_payload(error: str, message: str, **extra: Any) -> list[TextContent]:
+    """Return an MCP tool result envelope for an application-level error."""
+    payload: dict[str, Any] = {"error": error, "message": message, **extra}
+    return [TextContent(type="text", text=json.dumps(payload))]
+
+
+def _extract_text(content: list[dict[str, Any]]) -> str:
+    parts = []
+    for block in content:
+        if block.get("type") == "text":
+            parts.append(block.get("text", ""))
+    return "\n".join(parts)

agentlings/server.py

@@ -0,0 +1,247 @@
+"""Starlette application wiring A2A and MCP protocol endpoints on a single HTTP server."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+import uvicorn
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.routes.agent_card_routes import create_agent_card_routes
+from a2a.server.routes.jsonrpc_routes import create_jsonrpc_routes
+from mcp.server.streamable_http import StreamableHTTPServerTransport
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from agentlings.config import AgentConfig
+from agentlings.core.llm import create_llm_client
+from agentlings.core.loop import MessageLoop
+from agentlings.core.memory_store import MemoryFileStore
+from agentlings.core.scheduler import run_scheduler
+from agentlings.core.sleep import SleepCycle
+from agentlings.core.store import JournalStore
+from agentlings.core.telemetry import init_telemetry
+from agentlings.log import setup_logging
+from agentlings.protocol.a2a import AgentlingExecutor
+from agentlings.protocol.a2a_task_store import EngineTaskStore
+from agentlings.protocol.agent_card import generate_agent_card
+from agentlings.protocol.mcp import create_mcp_server
+from agentlings.tools.memory import init_memory_tool
+from agentlings.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+_PUBLIC_PATHS = {
+    "/.well-known/agent.json",
+    "/.well-known/agent-card.json",
+}
+
+
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    """Middleware that enforces ``X-API-Key`` header authentication on non-public paths."""
+
+    def __init__(self, app: Any, api_key: str) -> None:
+        super().__init__(app)
+        self._api_key = api_key
+
+    async def dispatch(self, request: Request, call_next: Any) -> Response:
+        """Check the API key header and reject unauthorized requests.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: Callable to pass the request to the next middleware or route.
+
+        Returns:
+            The downstream response, or a 401 JSON response if unauthorized.
+        """
+        if request.url.path in _PUBLIC_PATHS:
+            return await call_next(request)
+
+        key = request.headers.get("x-api-key", "")
+        if key != self._api_key:
+            return JSONResponse({"error": "Unauthorized"}, status_code=401)
+
+        return await call_next(request)
+
+
+def _create_app(config: AgentConfig | None = None) -> Starlette:
+    if config is None:
+        config = AgentConfig()
+
+    setup_logging(config.agent_log_level)
+
+    if config.telemetry_config:
+        init_telemetry(config.telemetry_config)
+
+    store = JournalStore(config.agent_data_dir)
+
+    memory_store: MemoryFileStore | None = None
+    if "memory" in config.enabled_tools or (
+        config.definition.memory is not None
+    ):
+        memory_store = MemoryFileStore(config.agent_data_dir)
+        init_memory_tool(memory_store)
+
+    tools = ToolRegistry()
+    tools.register_tools(config.enabled_tools, bash_timeout=config.definition.bash_timeout)
+
+    if not tools.tool_names():
+        logger.warning(
+            "no tools enabled — add tools to agent.yaml or set AGENT_CONFIG "
+            "(run 'agentling --list-tools' to see available options)"
+        )
+
+    llm = create_llm_client(
+        backend=config.agent_llm_backend,
+        api_key=config.anthropic_api_key,
+        model=config.agent_model,
+        max_tokens=config.agent_max_tokens,
+        tool_names=tools.tool_names(),
+        base_url=config.anthropic_base_url,
+    )
+
+    loop = MessageLoop(
+        config=config, store=store, llm=llm, tools=tools,
+        memory_store=memory_store,
+    )
+    # Startup crash recovery: reconcile orphaned task sub-journals and partial
+    # merge-backs before accepting new traffic.
+    try:
+        loop.engine.recover_on_startup()
+    except Exception:  # noqa: BLE001 — recovery is best-effort
+        logger.exception("crash recovery pass failed")
+
+    agent_card = generate_agent_card(config)
+
+    executor = AgentlingExecutor(loop, config)
+    request_handler = DefaultRequestHandler(
+        agent_executor=executor,
+        task_store=EngineTaskStore(loop.engine),
+        agent_card=agent_card,
+    )
+
+    mcp_server = create_mcp_server(loop=loop, agent_card=agent_card, config=config)
+    transport: StreamableHTTPServerTransport | None = None
+
+    async def mcp_endpoint(request: Request) -> Response:
+        assert transport is not None
+        await transport.handle_request(
+            request.scope, request.receive, request._send  # type: ignore[attr-defined]
+        )
+        return Response()
+
+    sleep_cycle: SleepCycle | None = None
+    if config.sleep_config and config.sleep_config.enabled and memory_store:
+        sleep_cycle = SleepCycle(
+            config=config, llm=llm, memory_store=memory_store, store=store,
+        )
+    elif config.sleep_config and not config.sleep_config.enabled:
+        logger.info("sleep cycle disabled by config (sleep.enabled=false)")
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[None]:
+        nonlocal transport
+        transport = StreamableHTTPServerTransport(mcp_session_id=None)
+
+        background_tasks: list[asyncio.Task[None]] = []
+
+        async with transport.connect() as (read_stream, write_stream):
+            mcp_task = asyncio.create_task(
+                mcp_server.run(
+                    read_stream,
+                    write_stream,
+                    mcp_server.create_initialization_options(),
+                )
+            )
+            background_tasks.append(mcp_task)
+
+            if sleep_cycle and config.sleep_config:
+                scheduler_task = asyncio.create_task(
+                    run_scheduler(
+                        expression=config.sleep_config.schedule,
+                        callback=sleep_cycle.run,
+                    )
+                )
+                background_tasks.append(scheduler_task)
+                logger.info(
+                    "sleep scheduler started: %s", config.sleep_config.schedule,
+                )
+
+            logger.info(
+                "agentling '%s' started on %s:%s",
+                config.agent_name,
+                config.agent_host,
+                config.agent_port,
+            )
+            try:
+                yield
+            finally:
+                # Drain live task workers before background services so
+                # merge-backs in flight complete against a valid store.
+                try:
+                    await loop.engine.shutdown()
+                except Exception:  # noqa: BLE001 — shutdown is best-effort
+                    logger.exception("task engine shutdown raised")
+
+                for t in background_tasks:
+                    t.cancel()
+                    try:
+                        await t
+                    except asyncio.CancelledError:
+                        pass
+
+    jsonrpc_routes = create_jsonrpc_routes(
+        request_handler=request_handler,
+        rpc_url="/a2a",
+        enable_v0_3_compat=True,
+    )
+    agent_card_routes = create_agent_card_routes(agent_card=agent_card)
+    # The 0.3 well-known path is ``/.well-known/agent.json``; 1.0 uses
+    # ``/.well-known/agent-card.json``. Expose both so existing 0.3 clients
+    # continue to discover the card.
+    legacy_card_routes = create_agent_card_routes(
+        agent_card=agent_card, card_url="/.well-known/agent.json"
+    )
+
+    routes = [
+        Route("/mcp", mcp_endpoint, methods=["GET", "POST", "DELETE"]),
+        *jsonrpc_routes,
+        *agent_card_routes,
+        *legacy_card_routes,
+    ]
+
+    middleware = [
+        Middleware(APIKeyMiddleware, api_key=config.agent_api_key),
+    ]
+
+    app = Starlette(
+        routes=routes,
+        middleware=middleware,
+        lifespan=lifespan,
+    )
+
+    return app
+
+
+def run(config: AgentConfig | None = None) -> None:
+    """Build the application and start the uvicorn server.
+
+    Args:
+        config: Optional agent configuration; defaults are loaded from the environment.
+    """
+    if config is None:
+        config = AgentConfig()
+
+    app = _create_app(config)
+    uvicorn.run(
+        app,
+        host=config.agent_host,
+        port=config.agent_port,
+        log_level=config.agent_log_level.lower(),
+    )

agentlings/templates/__init__.py

@@ -0,0 +1 @@
+"""Bundled agent templates used by ``agentling init --template <name>``."""

agentlings/templates/default/.env.example

@@ -0,0 +1,16 @@
+# Required: your Anthropic API key. Leave empty if pointing at an
+# Anthropic-compatible backend (e.g. Ollama) that ignores the header.
+ANTHROPIC_API_KEY=
+
+# Optional: override the Messages endpoint. Set to e.g. http://localhost:11434
+# to talk to Ollama's Anthropic-compatible API.
+# ANTHROPIC_BASE_URL=
+
+# Auto-generated by `agentling init`. This is the API key clients send
+# in the X-API-Key header to talk to this agent. Rotate by replacing.
+AGENT_API_KEY=
+
+# Optional overrides
+# AGENT_MODEL=claude-sonnet-4-6
+# AGENT_PORT=8420
+# AGENT_LOG_LEVEL=INFO

agentlings/templates/default/agent.yaml

@@ -0,0 +1,14 @@
+name: {{NAME}}
+description: A lightweight AI agent
+
+tools: []
+
+skills: []
+
+memory:
+  token_budget: 2000
+  inject_into_prompt: true
+
+sleep:
+  enabled: true
+  schedule: "0 2 * * *"

agentlings/tools/__init__.py

@@ -0,0 +1 @@
+"""Pluggable tool system with built-in bash and filesystem implementations."""