agstack 1.17.0__tar.gz → 1.18.0__tar.gz

{agstack-1.17.0 → agstack-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.17.0
+Version: 1.18.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.17.0 → agstack-1.18.0}/agstack/llm/flow/agent.py

@@ -88,6 +88,10 @@ class Agent:
     ) -> AsyncIterator[dict[str, Any]]:
         """流式执行 Agent，输出 AG-UI 标准事件"""
 
+        # 注入 agent_call_id 供 tool 审计关联
+        agent_call_id = str(uuid4())
+        context.set_variable("_agent_call_id", agent_call_id)
+
         # 输入来源：优先 inputs 参数，回退到 context.variables
         user_input = ""
         if inputs:
@@ -230,6 +234,7 @@ class Agent:
                 context.set_output(self.name, {"result": assistant_content})
                 # AG-UI: TEXT_MESSAGE_END
                 yield event.text_message_end(message_id=msg_id)
+                context.set_variable("_agent_call_id", None)
                 return
 
             # 执行工具调用
@@ -266,5 +271,10 @@ class Agent:
                 # AG-UI: TOOL_CALL_RESULT
                 yield event.tool_call_result(tool_call_id=tool_call["id"], content=result_content)
 
+                # 可观测性：yield tool 执行记录
+                for record in context.pop_execution_records():
+                    record["tool_call_id"] = tool_call["id"]
+                    yield event.custom(name="tool_execution", value=record)
+
             # 更新消息列表，继续下一轮
             messages = [self.get_system_message()] + context.history + context.get_messages(self.name)

{agstack-1.17.0 → agstack-1.18.0}/agstack/llm/flow/context.py

@@ -151,3 +151,9 @@ class FlowContext:
         if task_id is None:
             return self.execution_records
         return [r for r in self.execution_records if r.get("task_id") == task_id]
+
+    def pop_execution_records(self) -> list[dict[str, Any]]:
+        """取出并清空待发射的执行记录"""
+        records = self.execution_records
+        self.execution_records = []
+        return records

{agstack-1.17.0 → agstack-1.18.0}/agstack/llm/flow/nodes/base.py

@@ -48,4 +48,9 @@ class NodeHandler:
         yield event.step_started(step_name=step_name)
         result = await self.execute(node, context)
         context.set_output(node_id, result)
+
+        # 可观测性：drain tool 执行记录
+        for record in context.pop_execution_records():
+            yield event.custom(name="tool_execution", value=record)
+
         yield event.step_finished(step_name=step_name)

{agstack-1.17.0 → agstack-1.18.0}/agstack/llm/flow/tool.py

@@ -2,7 +2,9 @@
 
 """工具定义和执行"""
 
+import json
 import logging
+import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Callable
 
@@ -54,18 +56,38 @@ class Tool:
         self.echo = echo
 
     async def execute_async(self, context: "FlowContext", inputs: dict[str, Any] | None = None) -> ToolResult:
-        """异步执行工具"""
+        """异步执行工具（包含计时和可观测性记录）"""
+        args = inputs or {}
+        _t0 = time.perf_counter()
+        result = await self._execute(context, args)
+        _duration_ms = int((time.perf_counter() - _t0) * 1000)
+
+        result_content = json.dumps(result.result) if result.success else json.dumps({"error": result.error})
+        context.execution_records.append({
+            "agent_call_id": context.get_variable("_agent_call_id"),
+            "tool_name": self.name,
+            "tool_args": args,
+            "success": result.success,
+            "result": result_content,
+            "error": result.error,
+            "duration_ms": _duration_ms,
+        })
+
+        return result
+
+    async def _execute(self, context: "FlowContext", inputs: dict[str, Any]) -> ToolResult:
+        """实际执行逻辑，子类应覆写此方法"""
         try:
-            result = self.function(context, inputs or {})
+            result = self.function(context, inputs)
             if hasattr(result, "__await__"):
                 result = await result
 
-            return ToolResult(name=self.name, arguments=inputs or {}, result=result, success=True)
+            return ToolResult(name=self.name, arguments=inputs, result=result, success=True)
         except Exception as e:
             logger.warning("Tool %s failed: %s", self.name, e, exc_info=True)
             return ToolResult(
                 name=self.name,
-                arguments=inputs or {},
+                arguments=inputs,
                 result={},
                 success=False,
                 error=str(e),

{agstack-1.17.0 → agstack-1.18.0}/agstack/messagebus/redis.py

@@ -2,6 +2,7 @@
 
 import asyncio
 from collections.abc import AsyncIterator
+from typing import Self
 
 import redis.asyncio as aioredis
 from redis.asyncio.client import PubSub
@@ -17,15 +18,21 @@ class RedisSubscription(Subscription):
         self._channels = channels
         self._task: asyncio.Task[None] | None = None
         self._queue: asyncio.Queue[tuple[str, bytes]] = asyncio.Queue()
+        self._started = False
         self._closed = False
 
     async def _start(self) -> None:
-        """订阅 channel 并启动后台监听任务"""
+        if self._started:
+            return
+        self._started = True
         await self._pubsub.subscribe(*self._channels)
         self._task = asyncio.create_task(self._listen())
 
+    async def __aenter__(self) -> Self:
+        await self._start()
+        return self
+
     async def _listen(self) -> None:
-        """后台监听 Redis Pub/Sub 消息"""
         try:
             async for msg in self._pubsub.listen():
                 if self._closed:
@@ -47,6 +54,8 @@ class RedisSubscription(Subscription):
         return self
 
     async def __anext__(self) -> tuple[str, bytes]:
+        if not self._started:
+            await self._start()
         if self._closed and self._queue.empty():
             raise StopAsyncIteration
         try:
@@ -79,9 +88,7 @@ class RedisMessageBus(MessageBus):
 
     def subscribe(self, *channels: str) -> RedisSubscription:
         pubsub = self._client.pubsub()
-        sub = RedisSubscription(pubsub, channels)
-        # 调用方需要在 async with 或手动 await _start() 后使用
-        return sub
+        return RedisSubscription(pubsub, channels)
 
     async def close(self) -> None:
         await self._client.aclose()

{agstack-1.17.0 → agstack-1.18.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.17.0
+Version: 1.18.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.17.0 → agstack-1.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.17.0"
+version = "1.18.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"

{agstack-1.17.0 → agstack-1.18.0}/tests/test_messagebus_redis.py

@@ -26,40 +26,44 @@ async def bus():
 
 class TestPublishSubscribe:
     async def test_single_channel(self, bus: RedisMessageBus) -> None:
-        sub = bus.subscribe("test:ch1")
-        await sub._start()
-        async with sub:
+        async with bus.subscribe("test:ch1") as sub:
             await asyncio.sleep(0.1)
             await bus.publish("test:ch1", b"hello")
-            channel, message = await asyncio.wait_for(sub.__anext__(), timeout=3)
+            channel, message = await asyncio.wait_for(anext(sub), timeout=3)
             assert channel == "test:ch1"
             assert message == b"hello"
 
     async def test_multi_channel(self, bus: RedisMessageBus) -> None:
-        sub = bus.subscribe("test:ch1", "test:ch2")
-        await sub._start()
-        async with sub:
+        async with bus.subscribe("test:ch1", "test:ch2") as sub:
             await asyncio.sleep(0.1)
             await bus.publish("test:ch1", b"msg1")
             await bus.publish("test:ch2", b"msg2")
             results = []
             for _ in range(2):
-                ch, msg = await asyncio.wait_for(sub.__anext__(), timeout=3)
+                ch, msg = await asyncio.wait_for(anext(sub), timeout=3)
                 results.append((ch, msg))
             channels = [r[0] for r in results]
             assert "test:ch1" in channels
             assert "test:ch2" in channels
 
+    async def test_lazy_start_without_context_manager(self, bus: RedisMessageBus) -> None:
+        sub = bus.subscribe("test:ch1")
+        await asyncio.sleep(0.1)
+        await bus.publish("test:ch1", b"world")
+        channel, message = await asyncio.wait_for(anext(sub), timeout=3)
+        assert channel == "test:ch1"
+        assert message == b"world"
+        await sub.close()
+
     async def test_publish_no_subscribers(self, bus: RedisMessageBus) -> None:
         await bus.publish("test:nobody", b"lost message")
 
 
 class TestSubscriptionClose:
     async def test_close(self, bus: RedisMessageBus) -> None:
-        sub = bus.subscribe("test:ch1")
-        await sub._start()
-        await asyncio.sleep(0.1)
-        await sub.close()
+        async with bus.subscribe("test:ch1") as sub:
+            await asyncio.sleep(0.1)
+        assert sub._closed
 
 
 class TestBusClose: