agentkernel 0.9.1__tar.gz → 0.9.3__tar.gz

{agentkernel-0.9.1 → agentkernel-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.1
+Version: 0.9.3
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -140,7 +140,7 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
 - **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
 - **Session Management**: Built-in session abstraction with pluggable storage backends
-- **Knowledge Bases**: Unified `KnowledgeBase` interface with ChromaDB, Neo4j, and Starburst/Trino backends via `KnowledgeBuilder`
+- **Knowledge Bases**: Unified, capability-declaring `KnowledgeBase` interface with ChromaDB, Neo4j, Starburst/Trino and Open Knowledge Format bundle (local directory or S3) backends via `KnowledgeBuilder`
 - **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `kubernetes`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, per-user identity, and a queue-decoupled broker for long-running executions
 - **Scheduled Tasks**: Deferred and recurring chat execution (`schedule.at`/`schedule.cron`) with a management REST API, five agent-facing tools, and pluggable provider (`local`, `eventbridge`) and store (`in_memory`, `redis`, `valkey`, `dynamodb`) backends
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
@@ -165,6 +165,9 @@ pip install "agentkernel[neo4j]"
 pip install "agentkernel[trino]"
 ```
 
+Open Knowledge Format bundles need no extra - `pyyaml` is a core dependency. Serving a bundle from S3
+uses the `aws` extra: `pip install "agentkernel[aws]"`.
+
 For LLM-based thread naming with Conversation Thread Support:
 
 ```bash

{agentkernel-0.9.1 → agentkernel-0.9.3}/README.md

@@ -10,7 +10,7 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
 - **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
 - **Session Management**: Built-in session abstraction with pluggable storage backends
-- **Knowledge Bases**: Unified `KnowledgeBase` interface with ChromaDB, Neo4j, and Starburst/Trino backends via `KnowledgeBuilder`
+- **Knowledge Bases**: Unified, capability-declaring `KnowledgeBase` interface with ChromaDB, Neo4j, Starburst/Trino and Open Knowledge Format bundle (local directory or S3) backends via `KnowledgeBuilder`
 - **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `kubernetes`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, per-user identity, and a queue-decoupled broker for long-running executions
 - **Scheduled Tasks**: Deferred and recurring chat execution (`schedule.at`/`schedule.cron`) with a management REST API, five agent-facing tools, and pluggable provider (`local`, `eventbridge`) and store (`in_memory`, `redis`, `valkey`, `dynamodb`) backends
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
@@ -35,6 +35,9 @@ pip install "agentkernel[neo4j]"
 pip install "agentkernel[trino]"
 ```
 
+Open Knowledge Format bundles need no extra - `pyyaml` is a core dependency. Serving a bundle from S3
+uses the `aws` extra: `pip install "agentkernel[aws]"`.
+
 For LLM-based thread naming with Conversation Thread Support:
 
 ```bash

{agentkernel-0.9.1 → agentkernel-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.1"
+version = "0.9.3"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -230,3 +230,6 @@ target-version = ["py312"]
 
 [tool.pytest.ini_options]
 addopts = "--cov=src --cov-report=term --cov-report=html --html=report.html"
+# CI runs everything; `-m "not slow"` is for a local run that should not spend a minute
+# materialising a 10,000-concept bundle.
+markers = ["slow: builds a large fixture on disk or otherwise takes tens of seconds"]

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/api/handler.py

@@ -14,6 +14,8 @@ from ..core.runtime import Runtime
 
 
 class RESTRequestHandler(ABC):
+    requires_pipeline: bool = False
+
     @abstractmethod
     def get_router(self) -> APIRouter:
         """

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/api/http.py

@@ -105,11 +105,31 @@ class RESTAPI:
                 cls._log.info("in_memory queue transport resolved: starting the single-process pipeline topology")
                 return IOHandler.run()
 
+        handlers = handlers if handlers is not None else cls.get_default_handlers()
+        cls._reject_pipeline_only_handlers(handlers)
+
         host = AKConfig.get().api.host
         port = AKConfig.get().api.port
         cls._log.info(f"Agent Kernel REST API listening on http://{host}:{port}")
         uvicorn.run(app=cls.build_app(handlers), host=host, port=port, reload=False)
 
+    @classmethod
+    def _reject_pipeline_only_handlers(cls, handlers: list[RESTRequestHandler] = None) -> None:
+        """Refuse to serve a handler that only works inside the queue pipeline.
+
+        :param handlers: The handlers this run was asked to serve.
+        :raises AKConfigError: If any of them declares ``requires_pipeline``.
+        """
+        offenders = sorted({type(handler).__name__ for handler in handlers or [] if getattr(handler, "requires_pipeline", False) is True})
+        if offenders:
+            from ..core.util.factory import AKConfigError
+
+            raise AKConfigError(
+                f"{', '.join(offenders)} require the queue pipeline: serve them with "
+                "IOHandler.run(handlers=[...]) instead of RESTAPI.run([...]), which builds a bare "
+                "API with no runner to drain what they enqueue"
+            )
+
     @classmethod
     def build_app(cls, handlers: list[RESTRequestHandler] = None) -> FastAPI:
         """Assemble the complete FastAPI app (handlers, A2A/MCP mounts, custom routers) without serving it.

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/cli/cli.py

@@ -87,8 +87,8 @@ class CLI:
                 if not prompt.strip():
                     continue
                 if prompt.startswith("!"):
-                    tokens = prompt.lower().split()
-                    command = tokens[0]
+                    tokens = prompt.split()
+                    command = tokens[0].lower()  # only the command is case-insensitive; arguments are names
                     if command in ["!h", "!help"]:
                         self.help()
                     elif command in ["!c", "!clear"]:

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/core/base.py

@@ -5,7 +5,7 @@ import copy
 import logging
 import pickle
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator, Iterator, Mapping
+from collections.abc import AsyncGenerator, Iterable, Iterator, Mapping
 from enum import Enum
 from typing import Any, ClassVar, Self, cast
 
@@ -362,6 +362,22 @@ class Runner(ABC):
             exc_info=error,
         )
 
+    @staticmethod
+    def _native_kwargs(options: Mapping[str, Any], **ak_owned: Any) -> dict[str, Any]:
+        """
+        Builds the keyword arguments for a native framework run call from an agent's declared run options.
+        The declared options are copied first and the keys Agent Kernel owns are written last, so a declared
+        option can never displace a value the adapter populates itself (the same rule as `ak_tool_context` in
+        ADK and `messages` in LangGraph). The copy is shallow and per call: adjusting a value for one run never
+        touches the declared mapping.
+        :param options: The agent's declared run options (`Agent.run_options`, or an adapter's filtered view of it).
+        :param ak_owned: The keyword arguments the adapter populates itself; these win over `options`.
+        :return: A new dict holding the merged keyword arguments.
+        """
+        kwargs = dict(options)
+        kwargs.update(ak_owned)
+        return kwargs
+
     @abstractmethod
     async def run(self, agent: Any, session: Session, requests: list[AgentRequest]) -> AgentReply:
         """
@@ -411,6 +427,13 @@ class Agent(ABC):
 
     current_agent: ClassVar[contextvars.ContextVar["Agent | None"]] = contextvars.ContextVar("current_agent", default=None)
 
+    RESERVED_RUN_OPTIONS: ClassVar[Mapping[str, str]] = {}
+    """
+    Native run-call keyword arguments this adapter populates itself or depends on for reply mapping, mapped to
+    the one-line reason a caller sees when declaring one through `Module.run_options`. Empty on the base class,
+    so a bring-your-own Agent reserves nothing.
+    """
+
     @classmethod
     def current(cls) -> "Agent | None":
         """
@@ -430,6 +453,7 @@ class Agent(ABC):
         self._runner: Runner = runner
         self._pre_hooks: list[PreHook] = []
         self._post_hooks: list[PostHook] = []
+        self._run_options: dict[str, Any] = {}
 
     def __repr__(self) -> str:
         """
@@ -466,6 +490,28 @@ class Agent(ABC):
         """
         return self._post_hooks
 
+    @property
+    def run_options(self) -> dict[str, Any]:
+        """
+        Returns the framework-native keyword arguments merged into every native run call for this agent.
+        A live, mutable dict (the same contract as `pre_hooks`), declared through `Module.run_options` and never
+        persisted. Mutating it directly skips the reservation check entirely: a reserved key the runner writes itself
+        is overwritten, but one the adapter passes positionally raises the SDK's duplicate-argument error, and one
+        reserved only because it breaks the reply mapping is forwarded as given.
+        """
+        return self._run_options
+
+    def validate_run_options(self, options: Mapping[str, Any]) -> None:
+        """
+        Rejects run options that name a key this adapter reserves.
+        :param options: The run options about to be declared for this agent.
+        :raises ValueError: Naming the adapter, the agent, and every reserved key present with its reason.
+        """
+        reserved = sorted(set(options) & set(self.RESERVED_RUN_OPTIONS))
+        if reserved:
+            details = "; ".join(f"'{key}': {self.RESERVED_RUN_OPTIONS[key]}" for key in reserved)
+            raise ValueError(f"Run option(s) reserved by the '{self.runner.name}' adapter for agent '{self.name}': {details}")
+
     @contextlib.contextmanager
     def _activate(self) -> Iterator[Self]:
         """
@@ -533,9 +579,76 @@ class Agent(ABC):
         """
         from agentkernel.core.tool import SystemToolFactory
 
-        for tool in SystemToolFactory.get_all(self.name):
+        system_tools = SystemToolFactory.get_all(self.name)
+        self._warn_on_tool_name_collisions(system_tools)
+
+        for tool in system_tools:
             self.attach_tool(tool.func)
 
+    def _warn_on_tool_name_collisions(self, system_tools: list[Any]) -> None:
+        """
+        Warn when a system tool is about to shadow one the application already bound by hand.
+
+        Runs after the framework adapter has taken the built native agent, so tools the
+        application bound itself are already present and visible here. The collision is warned
+        about and then allowed: skipping would make newly enabling a capability silently do
+        nothing for this agent, which is the worse of the two failures. The cost is that both
+        tools reach the framework -- tolerated by some, rejected at bind time by others, with
+        this warning explaining why.
+
+        Entirely defensive: an adapter exposing no `tools` collection yields no warning, never
+        a raise.
+
+        :param system_tools: The SystemTool instances about to be attached.
+        :return: None.
+        """
+        native = getattr(self, "agent", None)
+        existing = {name for name in (self._native_tool_name(tool) for tool in self._native_tools(native)) if name}
+        colliding = sorted(existing.intersection(tool.name for tool in system_tools))
+        if colliding:
+            _log.warning(
+                "Agent '%s' already has tools named %s; Agent Kernel is attaching system tools with the same names. "
+                "The agent will carry both. If this agent was wired by hand, remove the manual binding or the configuration that enables it.",
+                self.name,
+                colliding,
+            )
+
+    @staticmethod
+    def _native_tools(native: Any) -> Iterable[Any]:
+        """
+        Return whatever the native agent holds its tools in, as something iterable.
+
+        Smolagents keys its tools by name -- `SmolagentsAgent._append_tools` writes
+        `agent.tools[name] = tool` -- so iterating the attribute directly yields names, not
+        tools. The keys are the names this warning is looking for, so the mapping is taken
+        through `keys()` and :meth:`_native_tool_name` accepts a bare string.
+
+        Anything that is neither a mapping nor a sequence yields nothing rather than raising,
+        which is what makes this method's caller safe against an adapter that means something
+        else entirely by `tools`.
+
+        :param native: The framework's own agent object, or None.
+        :return: The tools or tool names to inspect; empty when there are none to read.
+        """
+        tools = getattr(native, "tools", None)
+        if isinstance(tools, Mapping):
+            return tools.keys()
+        if isinstance(tools, (list, tuple, set, frozenset)):
+            return tools
+        return ()
+
+    @staticmethod
+    def _native_tool_name(tool: Any) -> str | None:
+        """
+        Name one tool the framework already holds.
+
+        :param tool: A tool object, or the name a mapping-shaped collection keyed it by.
+        :return: The tool's name, or None when it cannot be named.
+        """
+        if isinstance(tool, str):
+            return tool
+        return getattr(tool, "name", None) or getattr(tool, "__name__", None)
+
     @staticmethod
     def _append_tools(agent: Any, wrapped: list[Any]) -> None:
         """

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/core/chat_service.py

@@ -1,8 +1,8 @@
-import asyncio
 import base64
+import contextlib
 import json
 import logging
-from collections.abc import AsyncGenerator, Generator
+from collections.abc import AsyncGenerator, Generator, Iterator
 from typing import Any, Dict, List, Optional, Union
 
 from .config import AKConfig
@@ -21,6 +21,7 @@ from .model import (
     StreamChunk,
 )
 from .service import AgentService
+from .util.async_bridge import iterate_async_sync, run_async_sync
 
 
 class RequestBuilder:
@@ -138,6 +139,7 @@ class RequestBuilder:
             "schedule",
             "scheduled_task_id",
             "scheduled_time",
+            "requests",
         }
         for key, value in req.model_dump().items():
             if key in known_fields:
@@ -225,21 +227,25 @@ class AgentHandler:
     def _run_async_sync(coro) -> Any:
         """Run an async coroutine from sync code, handling event loop state.
 
-        Only a RuntimeError from get_event_loop() itself (no loop in this thread) falls back to
-        asyncio.run: a RuntimeError raised by the coroutine must propagate as-is, not trigger a
-        second await of the already-consumed coroutine.
+        Kept as a method because callers (and their tests) reach the bridge through it; the
+        loop handling itself is shared with the pipeline's synchronous consumers.
 
         :param coro: Coroutine to execute
         :return: Result of the coroutine
         """
-        try:
-            loop = asyncio.get_event_loop()
-        except RuntimeError:
-            return asyncio.run(coro)
-        if loop.is_closed():
-            asyncio.set_event_loop(asyncio.new_event_loop())
-            return asyncio.run(coro)
-        return loop.run_until_complete(coro)
+        return run_async_sync(coro)
+
+    @staticmethod
+    def _iterate_async_sync(agen) -> Iterator[Any]:
+        """Consume an async generator from sync code, handling event loop state.
+
+        The streaming sibling of _run_async_sync, and a method for the same reason: callers
+        (and their tests) reach the bridge through the handler.
+
+        :param agen: Async generator to consume
+        :return: Iterator over the generator's items
+        """
+        return iterate_async_sync(agen)
 
     def run_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> Any:
         """Run agent requests synchronously.
@@ -259,23 +265,17 @@ class AgentHandler:
         """
         return await self.service.run_multi(requests=requests, acting_user_id=acting_user_id)
 
-    def run_stream_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> List[Any]:
+    def run_stream_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> Iterator[Any]:
         """Run agent streaming requests synchronously.
 
-        Manages event loop lifecycle internally and returns all chunks as a list.
+        Manages event loop lifecycle internally and hands over each chunk as the run produces
+        it, so a sync consumer streams live instead of receiving the whole run at once.
 
         :param requests: List of AgentRequest objects to process
         :param acting_user_id: When given, published as the run's acting user (see Runtime.stream)
-        :return: List of StreamChunk objects
+        :return: Iterator of StreamChunk objects
         """
-
-        async def _collect():
-            chunks = []
-            async for chunk in self.service.stream_multi(requests=requests, acting_user_id=acting_user_id):
-                chunks.append(chunk)
-            return chunks
-
-        return AgentHandler._run_async_sync(_collect())
+        return AgentHandler._iterate_async_sync(self.service.stream_multi(requests=requests, acting_user_id=acting_user_id))
 
     async def run_stream_async(self, requests: List[Any], acting_user_id: Optional[str] = None) -> AsyncGenerator[Any, None]:
         """Run agent streaming requests asynchronously.
@@ -444,8 +444,9 @@ class ChatService:
     def execute_stream_sync(self, req: BaseRunRequest, requests: Optional[List[AgentRequest]] = None) -> Generator[StreamChunk, None, None]:
         """Synchronous counterpart of execute_stream().
 
-        Preserves the sync path's buffering semantics: AgentHandler.run_stream_sync collects
-        all chunks before this generator yields the first one.
+        Chunks arrive as the run produces them: AgentHandler.run_stream_sync pumps the async
+        stream one chunk at a time, so an exception mid-run reaches the caller as an error
+        chunk after the chunks already yielded, exactly as on the async path.
 
         :param req: Run request carrying prompt, agent, and session_id
         :param requests: Optional prebuilt AgentRequest list (see execute())
@@ -460,11 +461,12 @@ class ChatService:
         handler = self.prepare_agent_handler(req.session_id, req.agent)
 
         def _stream() -> Generator[StreamChunk, None, None]:
-            try:
-                for chunk in handler.run_stream_sync(requests, acting_user_id=req.user_id):
-                    yield chunk
-            except Exception as e:
-                yield StreamChunk(error=str(e), done=True)
+            with contextlib.closing(handler.run_stream_sync(requests, acting_user_id=req.user_id)) as chunks:
+                try:
+                    for chunk in chunks:
+                        yield chunk
+                except Exception as e:
+                    yield StreamChunk(error=str(e), done=True)
 
         return _stream()
 
@@ -575,15 +577,18 @@ class ChatService:
         self._validate(req, requests)
         return RequestBuilder.from_base_request_sync(req) if requests is None else requests
 
-    def process_chat_request(self, req: BaseRunRequest) -> Union[tuple[int, Dict[str, Any]], Dict[str, Any]]:
+    def process_chat_request(
+        self, req: BaseRunRequest, requests: Optional[List[AgentRequest]] = None
+    ) -> Union[tuple[int, Dict[str, Any]], Dict[str, Any]]:
         """Process a chat request synchronously.
 
         :param req: Base run request with prompt, session_id, agent, and attachments
+        :param requests: Optional prebuilt AgentRequest list (see execute_sync())
         :return: When rest_api_mode=False: tuple of (status_code, response_dict).
                  When rest_api_mode=True: response_dict only.
         """
         try:
-            result, session_id = self.execute_sync(req)
+            result, session_id = self.execute_sync(req, requests)
             return ResponseBuilder.build_response(self._success_status(req), session_id, self.rest_api_mode, result=result)
         except ValueError as ve:
             self._log.error(f"ValueError processing request: {ve}")
@@ -642,6 +647,7 @@ class ChatService:
         self,
         req: BaseRunRequest,
         sse_format: bool = False,
+        requests: Optional[List[AgentRequest]] = None,
     ) -> Generator[str, None, None]:
         """Process a streaming chat request synchronously.
 
@@ -652,19 +658,21 @@ class ChatService:
         :param req: Base run request with prompt, session_id, agent, and attachments
         :param sse_format: When True, yield Server-Sent Events formatted frames.
                            When False, yield raw StreamChunk JSON payloads.
+        :param requests: Optional prebuilt AgentRequest list (see execute_stream_sync())
         :return: Generator yielding StreamChunk payloads as JSON or SSE-formatted strings
         :raises ValueError: If session_id or prompt is missing, or no agent is available
         """
         session_id = req.session_id
-        chunks = self.execute_stream_sync(req)
+        chunks = self.execute_stream_sync(req, requests)
 
         def _stream() -> Generator[str, None, None]:
-            try:
-                for chunk in chunks:
-                    yield ResponseBuilder.stream_chunk(chunk, session_id, sse_format=sse_format)
-            except Exception as e:
-                error_chunk = StreamChunk(error=str(e), done=True)
-                yield ResponseBuilder.stream_chunk(error_chunk, session_id, sse_format=sse_format)
+            with contextlib.closing(chunks) as raw_chunks:
+                try:
+                    for chunk in raw_chunks:
+                        yield ResponseBuilder.stream_chunk(chunk, session_id, sse_format=sse_format)
+                except Exception as e:
+                    error_chunk = StreamChunk(error=str(e), done=True)
+                    yield ResponseBuilder.stream_chunk(error_chunk, session_id, sse_format=sse_format)
 
         return _stream()
 

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/core/config.py

@@ -161,6 +161,10 @@ class _SlackConfig(BaseModel):
         default="",
         description="The message to send as an acknowledgement when a Slack message is received",
     )
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Slack outbound adapter",
+    )
 
 
 class _WhatsAppConfig(BaseModel):
@@ -174,6 +178,10 @@ class _WhatsAppConfig(BaseModel):
     app_secret: str = Field(default="", description="WhatsApp app secret for signature verification")
     phone_number_id: str = Field(default="", description="WhatsApp Business phone number ID")
     api_version: str = Field(default="v24.0", description="WhatsApp API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in WhatsApp outbound adapter",
+    )
 
 
 class _MessengerConfig(BaseModel):
@@ -182,6 +190,10 @@ class _MessengerConfig(BaseModel):
     access_token: str = Field(default="", description="Facebook Page access token")
     app_secret: str = Field(default="", description="Facebook app secret for signature verification")
     api_version: str = Field(default="v24.0", description="Facebook Graph API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Facebook Messenger outbound adapter",
+    )
 
 
 class _InstagramConfig(BaseModel):
@@ -191,6 +203,10 @@ class _InstagramConfig(BaseModel):
     app_secret: str = Field(default="", description="Instagram app secret for signature verification")
     instagram_account_id: str = Field(default="", description="Instagram Business Account ID (IGSID)")
     api_version: str = Field(default="v21.0", description="Instagram Graph API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Instagram outbound adapter",
+    )
 
 
 class _TelegramConfig(BaseModel):
@@ -198,6 +214,10 @@ class _TelegramConfig(BaseModel):
     bot_token: str = Field(default="", description="Telegram bot token from BotFather")
     webhook_secret: str = Field(default="", description="Optional secret token for webhook security")
     api_version: str = Field(default="bot", description="Telegram Bot API version prefix")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Telegram outbound adapter",
+    )
 
 
 class _TeamsConfig(BaseModel):
@@ -212,6 +232,10 @@ class _TeamsConfig(BaseModel):
         default="",
         description="Entra ID tenant that owns the bot's app registration. Required only for a single-tenant registration, whose channel tokens must be issued by its own tenant; leave empty for a multi-tenant bot. Also the fallback tenant for the app-only token used to download attachments whose URL is not pre-authenticated, when the incoming activity carries none",
     )
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Microsoft Teams outbound adapter",
+    )
 
 
 class _GmailConfig(BaseModel):
@@ -219,6 +243,10 @@ class _GmailConfig(BaseModel):
     token_file: str = Field(default="token.pickle", description="Path to store OAuth2 token")
     poll_interval: int = Field(default=30, description="Email polling interval in seconds")
     label_filter: str = Field(default="INBOX", description="Gmail label to monitor (e.g., INBOX, UNREAD)")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Gmail outbound adapter",
+    )
 
 
 class _MultimodalStorageRedisConfig(_RedisConfig):
@@ -378,6 +406,52 @@ class _ScheduleConfig(BaseModel):
     )
 
 
+class _OKFDatabaseConfig(BaseModel):
+    """One Open Knowledge Format bundle and the agents that may reach it.
+
+    Permission is per (agent, database): an agent may produce into one bundle and only consume
+    another, and both hold at once.
+
+    The three role lists default to None rather than an empty list, so an omitted role reads as
+    "not declared" rather than "declared empty". At least one of them must name an agent; that
+    rule is enforced in OKFRoleRegistry.from_config rather than here, because a field validator
+    cannot see which database key it belongs to and so could not name it in the error."""
+
+    type: str = Field(description="Document store for this bundle: 'local', 's3', or a dotted path to a DocumentStore subclass")
+    uri: str = Field(
+        description="Bundle location passed to the resolved store: a filesystem path, an s3://bucket/prefix URI, or the store's own location string"
+    )
+    description: Optional[str] = Field(
+        default=None,
+        description="Human-readable description of this bundle, surfaced to the agent in its instructions and through get_schemas",
+    )
+    refresh_seconds: Optional[float] = Field(
+        default=300.0,
+        description="How stale the bundle manifest may get before the next operation re-walks the store; null disables automatic refresh",
+    )
+    consumer: Optional[list[str]] = Field(default=None, description="Agent names granted read access to this bundle")
+    producer: Optional[list[str]] = Field(
+        default=None,
+        description="Agent names granted read and write access, instructed to add new knowledge to this bundle",
+    )
+    curator: Optional[list[str]] = Field(
+        default=None,
+        description="Agent names granted read and write access, instructed to review and maintain existing knowledge in this bundle",
+    )
+
+
+class _OKFConfig(BaseModel):
+    """Configuration for the Open Knowledge Format capability.
+
+    The presence of the block is the enablement signal; naming an agent in a role is the
+    deliberate opt-in, and the block does nothing without at least one."""
+
+    databases: dict[str, _OKFDatabaseConfig] = Field(
+        default_factory=dict,
+        description="OKF bundles keyed by backend name; the key is what agents pass as the 'backend' argument to the knowledge-base tools",
+    )
+
+
 class _TraceConfig(BaseModel):
     enabled: bool = Field(default=False, description="Enable tracing")
     type: str = Field(
@@ -886,6 +960,11 @@ class AKConfig(YamlBaseSettingsModified):
         description="Scheduling capability configurations (trigger provider, task store, tool scoping). Absent = the capability is disabled.",
     )
 
+    okf: Optional[_OKFConfig] = Field(
+        default=None,
+        description="Open Knowledge Format capability configurations (bundles and the agents that consume, produce, or curate them). Absent = the capability is disabled.",
+    )
+
     trace: _TraceConfig = Field(description="Tracing related configurations", default_factory=_TraceConfig)
     guardrail: _GuardrailConfig = Field(description="Guardrail related configurations", default_factory=_GuardrailConfig)
     sandbox: _SandboxConfig = Field(description="Sandbox capability configurations", default_factory=_SandboxConfig)

{agentkernel-0.9.1 → agentkernel-0.9.3}/src/agentkernel/core/model.py

@@ -1,9 +1,9 @@
 import json
 import uuid
 from enum import Enum
-from typing import Any, Callable, List, Literal, Optional, Union
+from typing import Annotated, Any, Callable, List, Literal, Optional, Union
 
-from pydantic import BaseModel, ConfigDict, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .event import StreamEvent
 
@@ -125,6 +125,11 @@ class AgentReplyImage(AgentRequestImage):
 type AgentRequest = Union[AgentRequestText, AgentRequestFile, AgentRequestImage, AgentRequestAny, AgentRequestAttachmentRef]
 type AgentReply = Union[AgentReplyText, AgentReplyImage, AgentReplyAny]
 
+AgentRequestUnion = Annotated[
+    Union[AgentRequestText, AgentRequestFile, AgentRequestImage, AgentRequestAny, AgentRequestAttachmentRef],
+    Field(discriminator="type"),
+]
+
 
 class AgentReplyAny(BaseModel):
     """
@@ -268,10 +273,18 @@ class BaseRunRequest(BaseChatRequest):
     it delivers, identifying the task and the occurrence this run belongs to. They are
     typed fields (not extras) so an occurrence's metadata never reaches the agent as
     additional context.
+
+    requests carries an already-built AgentRequest list, for producers that compose it
+    themselves rather than leaving it to RequestBuilder: a messaging integration downloads
+    its attachments at the edge and stores them, so what reaches the queue is a request list
+    (including AgentRequestAttachmentRef entries, which files/images cannot express). Typed
+    for the same reason as the scheduling fields: an extra would reach the agent as
+    AgentRequestAny context.
     """
 
     files: Optional[List[FileData]] = None
     images: Optional[List[ImageData]] = None
+    requests: Optional[List[AgentRequestUnion]] = None
     scheduled_task_id: Optional[str] = None
     scheduled_time: Optional[str] = None
     model_config = ConfigDict(extra="allow")