zero-agent-core 0.2.0__py3-none-any.whl

agent_core/tools/executor.py

@@ -0,0 +1,306 @@
+"""手写工具执行器。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_core.protocol.runtime import ToolResult
+
+logger = logging.getLogger(__name__)
+
+# 工具函数签名
+ToolFunc = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """工具的可执行元数据，和工具函数本身分离。"""
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    risk_level: str = "read"
+    requires_approval: bool = False
+    timeout_seconds: float | None = None
+    idempotent: bool = True
+
+
+class ToolRegistry:
+    """工具注册表。
+
+    管理所有可用的工具函数。
+    """
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolFunc] = {}
+        self._specs: dict[str, ToolSpec] = {}
+
+    def register(
+        self,
+        name: str,
+        func: ToolFunc,
+        description: str,
+        *,
+        parameters: dict[str, Any] | None = None,
+        risk_level: str = "read",
+        requires_approval: bool = False,
+        timeout_seconds: float | None = None,
+        idempotent: bool = True,
+    ) -> None:
+        """注册一个工具。
+
+        Args:
+            name: 工具名称（全局唯一）。
+            func: 工具函数（可以是同步或异步）。
+            description: 工具描述（供 LLM 理解用途）。
+        """
+        if name in self._tools:
+            logger.warning("Tool %r already registered, overwriting", name)
+        self._tools[name] = func
+        self._specs[name] = ToolSpec(
+            name=name,
+            description=description,
+            parameters=parameters or {"type": "object", "properties": {}, "required": []},
+            risk_level=risk_level,
+            requires_approval=requires_approval,
+            timeout_seconds=timeout_seconds,
+            idempotent=idempotent,
+        )
+        logger.debug("Registered tool: %r", name)
+
+    def get_tool(self, name: str) -> ToolFunc | None:
+        """获取工具函数。"""
+        return self._tools.get(name)
+
+    def get_all_tools(self) -> dict[str, ToolFunc]:
+        """获取所有工具。"""
+        return self._tools.copy()
+
+    def get_tool_names(self) -> list[str]:
+        """获取所有工具名称。"""
+        return list(self._tools.keys())
+
+    def get_spec(self, name: str) -> ToolSpec | None:
+        """获取工具策略和参数 schema。"""
+        return self._specs.get(name)
+
+    def get_all_specs(self) -> dict[str, ToolSpec]:
+        return self._specs.copy()
+
+    def build_tool_definitions(self) -> list[dict[str, Any]]:
+        """构造 OpenAI function calling 格式的工具定义列表。
+
+        返回注册时声明的完整参数 schema。
+        """
+        definitions = []
+        for name, spec in self._specs.items():
+            definitions.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": name,
+                        "description": spec.description,
+                        "parameters": spec.parameters,
+                    },
+                }
+            )
+        return definitions
+
+
+class ToolExecutor:
+    """工具执行器。
+
+    负责根据 tool_call 执行对应的工具函数。
+    """
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        *,
+        approval_callback: Callable[[ToolSpec, dict[str, Any]], Awaitable[bool]] | None = None,
+    ) -> None:
+        self._registry = registry
+        self._approval_callback = approval_callback
+
+    async def execute(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        approval_granted: bool | None = None,
+    ) -> str:
+        """执行单个工具调用。
+
+        Args:
+            tool_name: 工具名称。
+            arguments: 工具参数。
+
+        Returns:
+            工具执行结果（字符串格式）。
+        """
+        result = await self.execute_result(
+            tool_name,
+            arguments,
+            approval_granted=approval_granted,
+        )
+        return result.to_text()
+
+    async def execute_result(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        approval_granted: bool | None = None,
+    ) -> ToolResult:
+        """执行工具并返回结构化结果。
+
+        ``approval_granted`` 用于已经在 API 或工作流边界完成审批的调用。
+        未显式传入时仍使用构造器注入的审批回调，避免普通 Agent Loop 绕过审批。
+        """
+        tool_func = self._registry.get_tool(tool_name)
+        if tool_func is None:
+            error_msg = f"Tool {tool_name!r} not found."
+            logger.warning(error_msg)
+            return ToolResult(
+                tool_name=tool_name,
+                success=False,
+                error=error_msg,
+                error_kind="not_found",
+            )
+
+        if not isinstance(arguments, dict):
+            return ToolResult(
+                tool_name=tool_name,
+                success=False,
+                error="arguments 必须是对象",
+                error_kind="invalid_arguments",
+            )
+
+        spec = self._registry.get_spec(tool_name)
+        if spec is not None:
+            schema_error = self._validate_arguments(spec, arguments)
+            if schema_error:
+                return ToolResult(
+                    tool_name=tool_name,
+                    success=False,
+                    error=schema_error,
+                    error_kind="invalid_arguments",
+                )
+            if spec.requires_approval:
+                if approval_granted is True:
+                    pass
+                elif approval_granted is False:
+                    return ToolResult(
+                        tool_name=tool_name,
+                        success=False,
+                        error="审批拒绝",
+                        error_kind="approval",
+                    )
+                elif self._approval_callback is None:
+                    return ToolResult(
+                        tool_name=tool_name,
+                        success=False,
+                        error="未配置审批回调",
+                        error_kind="approval",
+                    )
+                else:
+                    try:
+                        approved = await self._approval_callback(spec, arguments)
+                    except Exception as exc:
+                        logger.warning("工具 %r 审批回调失败：%s", tool_name, exc, exc_info=True)
+                        return ToolResult(
+                            tool_name=tool_name,
+                            success=False,
+                            error=f"审批回调失败：{exc}",
+                            error_kind="approval",
+                            retryable=True,
+                        )
+                    if not approved:
+                        return ToolResult(
+                            tool_name=tool_name,
+                            success=False,
+                            error="审批拒绝",
+                            error_kind="approval",
+                        )
+
+        try:
+            logger.debug("Executing tool: %r with args: %s", tool_name, arguments)
+
+            async def invoke() -> Any:
+                if asyncio.iscoroutinefunction(tool_func):
+                    return await tool_func(**arguments)
+                # 同步工具放到线程，避免阻塞 Agent Loop。
+                return await asyncio.to_thread(tool_func, **arguments)
+
+            if spec and spec.timeout_seconds:
+                result = await asyncio.wait_for(invoke(), spec.timeout_seconds)
+            else:
+                result = await invoke()
+
+            return ToolResult(tool_name=tool_name, success=True, value=result)
+
+        except TimeoutError:
+            logger.warning("Tool %r timed out", tool_name)
+            return ToolResult(
+                tool_name=tool_name,
+                success=False,
+                error="工具执行超时",
+                error_kind="timeout",
+                retryable=True,
+            )
+        except Exception as exc:
+            logger.warning("Tool %r raised exception: %s", tool_name, exc, exc_info=True)
+            return ToolResult(
+                tool_name=tool_name,
+                success=False,
+                error=str(exc),
+                error_kind="execution",
+                retryable=False,
+            )
+
+    @staticmethod
+    def _validate_arguments(spec: ToolSpec, arguments: dict[str, Any]) -> str | None:
+        """执行一层无第三方依赖的基本 schema 校验。"""
+        schema = spec.parameters or {}
+        required = schema.get("required", [])
+        missing = [name for name in required if name not in arguments]
+        if missing:
+            return f"缺少必填参数：{', '.join(str(item) for item in missing)}"
+        properties = schema.get("properties", {})
+        for name, value in arguments.items():
+            if name not in properties and schema.get("additionalProperties") is False:
+                return f"参数 {name} 未在工具 schema 中声明"
+            definition = properties.get(name, {})
+            expected = definition.get("type")
+            if expected == "string" and not isinstance(value, str):
+                return f"参数 {name} 必须是字符串"
+            if expected == "number" and (not isinstance(value, (int, float)) or isinstance(value, bool)):
+                return f"参数 {name} 必须是数字"
+            if expected == "integer" and (not isinstance(value, int) or isinstance(value, bool)):
+                return f"参数 {name} 必须是整数"
+            if expected == "boolean" and not isinstance(value, bool):
+                return f"参数 {name} 必须是布尔值"
+            if expected == "array" and not isinstance(value, list):
+                return f"参数 {name} 必须是数组"
+            if expected == "object" and not isinstance(value, dict):
+                return f"参数 {name} 必须是对象"
+        return None
+
+    async def execute_batch(
+        self,
+        tool_calls: list[dict[str, Any]],
+    ) -> list[str]:
+        """并发执行多个工具调用。
+
+        Args:
+            tool_calls: 工具调用列表，每个包含 name 和 args。
+
+        Returns:
+            工具执行结果列表（与 tool_calls 顺序对应）。
+        """
+        tasks = [self.execute(tc["name"], tc.get("args", {})) for tc in tool_calls]
+        return await asyncio.gather(*tasks)

agent_core/workflow/__init__.py

@@ -0,0 +1,25 @@
+"""通用状态机和持久化工作流运行器。"""
+
+from agent_core.workflow.durable import DurableWorkflowRunner
+from agent_core.workflow.state_machine import (
+    END,
+    START,
+    NodeExecutionContext,
+    NodeExecutionPolicy,
+    StateMachine,
+    StateMachineBuilder,
+    WorkflowPause,
+    current_node_execution,
+)
+
+__all__ = [
+    "END",
+    "START",
+    "DurableWorkflowRunner",
+    "NodeExecutionContext",
+    "NodeExecutionPolicy",
+    "StateMachine",
+    "StateMachineBuilder",
+    "WorkflowPause",
+    "current_node_execution",
+]

agent_core/workflow/durable.py

@@ -0,0 +1,175 @@
+"""状态机与工作流执行存储的持久化运行器。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_core.access import AccessContext, enforce_access
+from agent_core.storage.workflow import WorkflowExecution, WorkflowExecutionStore
+from agent_core.workflow.state_machine import (
+    END,
+    START,
+    NodeExecutionContext,
+    StateMachine,
+    WorkflowPause,
+)
+
+
+class DurableWorkflowRunner:
+    """在每个节点边界保存状态，并支持进程重启后继续执行。"""
+
+    def __init__(
+        self,
+        machine: StateMachine,
+        store: WorkflowExecutionStore,
+        *,
+        require_access: bool = False,
+        raise_on_failure: bool = True,
+    ) -> None:
+        self._machine = machine
+        self._store = store
+        self._strict_access = require_access
+        self._raise_on_failure = raise_on_failure
+
+    async def start(
+        self,
+        definition_id: str,
+        initial_state: dict[str, Any],
+        *,
+        execution_type: str = "workflow",
+        access: AccessContext | None = None,
+    ) -> WorkflowExecution:
+        """创建执行实例并运行到完成、暂停或失败。"""
+        if self._strict_access and access is None:
+            raise PermissionError("该 DurableWorkflowRunner 要求提供 AccessContext")
+        execution = WorkflowExecution(
+            definition_id=definition_id,
+            execution_type=execution_type,
+            user_id=access.user_id if access else None,
+            tenant_id=access.tenant_id if access else None,
+            status="queued",
+            current_step=START,
+            total_steps=self._machine.node_count,
+            input_data=dict(initial_state),
+            result_data=dict(initial_state),
+            events=[{"event_type": "workflow_queued", "step": START}],
+        )
+        await self._store.save(execution)
+        return await self._run(execution)
+
+    async def resume(
+        self,
+        execution_id: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> WorkflowExecution:
+        """从最后保存的下一节点继续执行。"""
+        execution = await self._store.load(execution_id)
+        if execution is None:
+            raise KeyError(f"工作流执行实例不存在：{execution_id}")
+        self._check_access(execution, access)
+        if execution.status == "completed":
+            return execution
+        if execution.current_step == END:
+            execution.status = "completed"
+            await self._store.save(execution)
+            return execution
+        execution.events.append({"event_type": "workflow_resumed", "step": execution.current_step or START})
+        return await self._run(execution)
+
+    async def _run(self, execution: WorkflowExecution) -> WorkflowExecution:
+        execution.status = "running"
+        await self._store.save(execution)
+        completed_offset = execution.steps_completed
+
+        def idempotency_key(node_name: str, completed_nodes: int) -> str:
+            sequence = completed_offset + completed_nodes + 1
+            return f"{execution.execution_id}:{sequence}:{node_name}"
+
+        async def persist_pending(context: NodeExecutionContext, _state: dict[str, Any]) -> None:
+            execution.events.append(
+                {
+                    "event_type": "workflow_step_pending",
+                    "step": context.node_name,
+                    "attempt": context.attempt,
+                    "idempotency_key": context.idempotency_key,
+                }
+            )
+            await self._store.save(execution)
+
+        async def persist_step(
+            current_node: str,
+            next_node: str,
+            state: dict[str, Any],
+            completed_nodes: int,
+        ) -> None:
+            execution.current_step = next_node
+            execution.steps_completed = completed_offset + completed_nodes
+            execution.result_data = state
+            execution.events.append(
+                {
+                    "event_type": "workflow_step_completed",
+                    "step": current_node,
+                    "next_step": next_node,
+                    "idempotency_key": idempotency_key(current_node, completed_nodes - 1),
+                }
+            )
+            await self._store.save(execution)
+
+        try:
+            result = await self._machine.ainvoke_from(
+                execution.result_data,
+                start_node=execution.current_step or START,
+                on_step=persist_step,
+                on_node_start=persist_pending,
+                idempotency_key_factory=idempotency_key,
+            )
+        except WorkflowPause as exc:
+            execution.status = "interrupted"
+            execution.events.append(
+                {
+                    "event_type": "workflow_interrupted",
+                    "step": execution.current_step,
+                    "reason": exc.reason,
+                    "data": exc.data,
+                }
+            )
+            await self._store.save(execution)
+            return execution
+        except Exception as exc:
+            execution.status = "failed"
+            execution.events.append(
+                {
+                    "event_type": "workflow_failed",
+                    "step": execution.current_step,
+                    "error": str(exc),
+                }
+            )
+            await self._store.save(execution)
+            if self._raise_on_failure:
+                raise
+            return execution
+
+        execution.status = "completed"
+        execution.current_step = END
+        execution.result_data = result
+        execution.events.append({"event_type": "workflow_completed", "step": END})
+        await self._store.save(execution)
+        return execution
+
+    def _check_access(
+        self,
+        execution: WorkflowExecution,
+        access: AccessContext | None,
+    ) -> None:
+        enforce_access(
+            strict=self._strict_access,
+            accessor="DurableWorkflowRunner",
+            subject="工作流执行实例",
+            owner_user_id=execution.user_id,
+            owner_tenant_id=execution.tenant_id,
+            access=access,
+        )
+
+
+__all__ = ["DurableWorkflowRunner"]