agentkernel 0.9.0__tar.gz → 0.9.2__tar.gz

{agentkernel-0.9.0 → agentkernel-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.0
+Version: 0.9.2
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -44,7 +44,7 @@ Requires-Dist: nest-asyncio>=1.6.0 ; extra == 'langfuse'
 Requires-Dist: langgraph~=1.2.10 ; extra == 'langgraph'
 Requires-Dist: langgraph-prebuilt~=1.1.0 ; extra == 'langgraph'
 Requires-Dist: langchain~=1.3.10 ; extra == 'langgraph'
-Requires-Dist: langchain-community==0.4.1 ; extra == 'langgraph'
+Requires-Dist: langchain-community~=0.4.1 ; extra == 'langgraph'
 Requires-Dist: litellm~=1.89.2 ; extra == 'langgraph'
 Requires-Dist: logfire>=3.0 ; extra == 'logfire'
 Requires-Dist: fastmcp>=3.2.0,<4.0.0 ; extra == 'mcp'
@@ -57,6 +57,7 @@ Requires-Dist: openai-agents>=0.7.0 ; extra == 'openai'
 Requires-Dist: openinference-instrumentation-openai-agents>=1.4.0 ; extra == 'openai'
 Requires-Dist: openai-guardrails>=0.2.1 ; extra == 'openai'
 Requires-Dist: traceloop-sdk>=0.61.0 ; extra == 'openllmetry'
+Requires-Dist: opik>=1.7.0 ; extra == 'opik'
 Requires-Dist: pydantic-ai-slim~=2.13.0 ; extra == 'pydanticai'
 Requires-Dist: openinference-instrumentation-pydantic-ai>=0.1.17 ; extra == 'pydanticai'
 Requires-Dist: redis>=7.1.0 ; extra == 'redis'
@@ -111,6 +112,7 @@ Provides-Extra: nats
 Provides-Extra: neo4j
 Provides-Extra: openai
 Provides-Extra: openllmetry
+Provides-Extra: opik
 Provides-Extra: pydanticai
 Provides-Extra: redis
 Provides-Extra: sandbox-docker
@@ -1261,7 +1263,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name, or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1283,8 +1285,8 @@ Configure test comparison modes for automated testing. Test configuration is sep
   - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in DeepEval evaluator: `Scorer.quasi_exact_match_score`)
-- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in DeepEval evaluator: `GEval`) for semantic similarity
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `pip install "agentkernel[opik]"`)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1646,7 +1648,7 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export LOGFIRE_TOKEN=your-write-token
 # Test harness (loaded from the separate test-config.yaml — see Test Configuration)
 export AK_TEST__MODE=fallback  # Options: score, llm, fallback
-export AK_TEST__EVALUATOR=deepeval  # Built-in short name, or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval or opik), or a dotted path to your own AKEvaluator subclass
 export AK_TEST__LLM__MODEL=gpt-4o-mini
 export AK_TEST__LLM__PROVIDER=openai
 export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
@@ -1916,6 +1918,8 @@ gmail:
 
 Test harness configuration (comparison mode, evaluator backend, llm models) is separate from the application configuration. It is not part of `config.yaml` — it lives in its own `test-config.yaml` file, resolved from the current working directory, and is only loaded when the testing utilities (`agentkernel.test`) are used. A legacy `test:` section in `config.yaml` is ignored. See [Test Configuration](#test-configuration) under Configuration Options for the full list of fields and defaults.
 
+The `evaluator` field accepts two built-in short names — `deepeval` (default, `pip install "agentkernel[test]"`) or `opik` (`pip install "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) — or a dotted path to your own `AKEvaluator` subclass.
+
 **test-config.yaml:**
 
 ```yaml

{agentkernel-0.9.0 → agentkernel-0.9.2}/README.md

@@ -1133,7 +1133,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name, or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1155,8 +1155,8 @@ Configure test comparison modes for automated testing. Test configuration is sep
   - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in DeepEval evaluator: `Scorer.quasi_exact_match_score`)
-- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in DeepEval evaluator: `GEval`) for semantic similarity
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `pip install "agentkernel[opik]"`)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1518,7 +1518,7 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export LOGFIRE_TOKEN=your-write-token
 # Test harness (loaded from the separate test-config.yaml — see Test Configuration)
 export AK_TEST__MODE=fallback  # Options: score, llm, fallback
-export AK_TEST__EVALUATOR=deepeval  # Built-in short name, or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval or opik), or a dotted path to your own AKEvaluator subclass
 export AK_TEST__LLM__MODEL=gpt-4o-mini
 export AK_TEST__LLM__PROVIDER=openai
 export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
@@ -1788,6 +1788,8 @@ gmail:
 
 Test harness configuration (comparison mode, evaluator backend, llm models) is separate from the application configuration. It is not part of `config.yaml` — it lives in its own `test-config.yaml` file, resolved from the current working directory, and is only loaded when the testing utilities (`agentkernel.test`) are used. A legacy `test:` section in `config.yaml` is ignored. See [Test Configuration](#test-configuration) under Configuration Options for the full list of fields and defaults.
 
+The `evaluator` field accepts two built-in short names — `deepeval` (default, `pip install "agentkernel[test]"`) or `opik` (`pip install "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) — or a dotted path to your own `AKEvaluator` subclass.
+
 **test-config.yaml:**
 
 ```yaml

{agentkernel-0.9.0 → agentkernel-0.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.0"
+version = "0.9.2"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -43,7 +43,7 @@ langgraph = [
     "langgraph~=1.2.10",
     "langgraph-prebuilt~=1.1.0",
     "langchain~=1.3.10",
-    "langchain_community==0.4.1",
+    "langchain_community~=0.4.1",
     "litellm~=1.89.2"
 ]
 smolagents = [
@@ -188,6 +188,9 @@ daytona = [
 kubernetes = [
     "kubernetes>=29.0.0",
 ]
+opik = [
+    "opik>=1.7.0",
+]
 
 [project.scripts]
 ak = "agentkernel.cli.ak:main"

{agentkernel-0.9.0 → agentkernel-0.9.2}/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.0 → agentkernel-0.9.2}/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.0 → agentkernel-0.9.2}/src/agentkernel/core/__init__.py

@@ -44,7 +44,7 @@ from .config import AKConfig as Config
 from .module import Module
 from .runtime import ACTING_USER_CACHE_KEY, Runtime
 from .service import AgentService
-from .hooks import PreHook, PostHook
+from .hooks import PreHook, PostHook, StreamHalt
 from .tool import ToolContext, ToolBuilder
 from .util.key_value_cache import KeyValueCache
 from .chat_service import ChatService

{agentkernel-0.9.0 → agentkernel-0.9.2}/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.0 → agentkernel-0.9.2}/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):

{agentkernel-0.9.0 → agentkernel-0.9.2}/src/agentkernel/core/hooks.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from .base import Agent, Session
 
+from .event import StreamEvent
 from .model import AgentReply, AgentRequest
 
 """
@@ -16,6 +17,26 @@ Currently, they will get only called for the initial execution of an agent when
 """
 
 
+class StreamHalt(Exception):
+    """
+    Raised by a post-hook to end a streamed run early.
+
+    Runtime.stream catches it, emits the closing event for any boundary the stream left open, and
+    yields one terminal StreamChunk carrying `reason` as its error. The session is not stored, so a
+    halted turn leaves no trace in conversation state.
+
+    The partial response is invalid rather than merely truncated: a client must discard what it has
+    already rendered instead of presenting it as a short answer.
+    """
+
+    def __init__(self, reason: str):
+        """
+        :param reason: Why the run was halted. Reaches the client verbatim as StreamChunk.error.
+        """
+        super().__init__(reason)
+        self.reason = reason
+
+
 class PreHook(ABC):
     @abstractmethod
     async def on_run(self, session: "Session", agent: "Agent", requests: list[AgentRequest]) -> list[AgentRequest] | AgentReply:
@@ -70,19 +91,38 @@ class PostHook(ABC):
         """
         raise NotImplementedError
 
-    async def on_stream_chunk(
+    async def on_stream_event(
         self,
         session: "Session",
         requests: list[AgentRequest],
         agent: "Agent",
-        delta: str,
-    ) -> str | None:
+        event: StreamEvent,
+    ) -> StreamEvent | list[StreamEvent] | None:
         """
-        Called for each streaming token delta before it is sent to the client.
-        Return the (optionally modified) delta string, or None to drop the token.
-        Default implementation passes the delta through unchanged.
+        Hook method called for every event a streamed run produces, before it reaches the client.
+
+        Unlike on_run, this sees the whole stream: message and reasoning text, tool call names,
+        arguments and results, and the boundaries that pair them.
+
+        Returning a list emits several events in place of one, which is what makes hold-and-release
+        possible: return None per fragment while accumulating in the session's volatile cache, then
+        return [rewritten_payload, closing_event] at the boundary. Accumulate there, not on `self` —
+        one hook instance serves every concurrent request. A returned list is emitted as-is and ends
+        the chain for that event, so `return event` and `return [event]` are not equivalent.
+
+        :param: session (Session): The session instance.
+        :param: requests (list[AgentRequest]): The requests provided to the agent, after pre-hooks.
+        :param: agent (Agent): The agent being streamed.
+        :param: event (StreamEvent): The event to process, as produced by the runner or by an
+                              earlier hook in the chain.
+        :return:
+                - StreamEvent: The event, or a modified event of the same `type`, to pass on. A
+                               different `type` raises TypeError; use a list to emit another type.
+                - list[StreamEvent]: Emitted in order, in place of `event`, ending the chain for it.
+                - None: Drops the event; nothing is sent to the client for it.
+        :raises StreamHalt: To end the run without emitting anything further.
         """
-        return delta
+        return event
 
     @abstractmethod
     def name(self) -> str:

{agentkernel-0.9.0 → agentkernel-0.9.2}/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")

{agentkernel-0.9.0 → agentkernel-0.9.2}/src/agentkernel/core/multimodal/storage/__init__.py

@@ -1,8 +1,10 @@
-"""
-Storage sub-package for multimodal attachments.
-
-Provides pluggable storage backends (in_memory, session_cache, redis, dynamodb)
-and the ``AttachmentStorageManager`` high-level API.
-"""
-
-from .storage_manager import AttachmentStorageManager
+"""
+Storage sub-package for multimodal attachments.
+
+Provides pluggable storage backends (in_memory, session_cache, redis, dynamodb)
+and the ``AttachmentStorageManager`` high-level API.
+"""
+
+from .storage_manager import AttachmentStorageManager, StoredAttachment
+
+__all__ = ["AttachmentStorageManager", "StoredAttachment"]