spineagent 0.0.1__py3-none-any.whl

spineagent/__init__.py

@@ -0,0 +1,121 @@
+"""spineagent —— 通用多 agent 协作框架(ADR 0001 D1),依赖薄核 corespine。
+
+agent / tool / 编排 + MCP / A2A 协议缝。复用 corespine 的缝元模式(Protocol + 离线确定性
+默认 + Registry 工厂 + 参数化 conformance)、隐私安全 observability 与 env 配置风格;核心
+默认路径【零网络、零重依赖、离线可跑】,真实协议 SDK 仅经可选 extra 延迟 import。
+
+运行时可把 ragspine 当作一个 Tool / MCP server 在【运行时】组合调用(ADR 0001 D4b),但本包
+【不】在包层面依赖 ragspine。详见 CLAUDE.md 宪章与家族 ADR 0001。
+"""
+
+from spineagent.agent.agent import Agent, AgentResult, FunctionAgent, LlmAgent
+from spineagent.agent.as_tool import AgentTool
+from spineagent.agent.function_calling import FunctionCallingAgent
+from spineagent.agent.policy import (
+    Action,
+    Finish,
+    Observation,
+    SyntaxToolPolicy,
+    ToolCall,
+    ToolPolicy,
+    tool_policies,
+)
+from spineagent.agent.tool_using import ToolUsingAgent
+from spineagent.conformance import AGENT_INVARIANTS, POLICY_INVARIANTS, TOOL_INVARIANTS
+from spineagent.llm.bedrock_provider import BedrockConverseProvider, load_boto3_sdk
+from spineagent.llm.cohere_provider import CohereProvider, load_cohere_sdk
+from spineagent.llm.gemini_provider import GeminiProvider, load_gemini_sdk
+from spineagent.llm.provider import (
+    AnthropicProvider,
+    OpenAICompatProvider,
+    llm_providers,
+    load_anthropic_sdk,
+    load_openai_sdk,
+)
+from spineagent.orchestration.chain import ChainAgent
+from spineagent.orchestration.coordinator import Coordinator
+from spineagent.protocol.a2a.seam import (
+    A2AAgent,
+    A2AAgentAdapter,
+    A2AResult,
+    A2ATask,
+    OfflineA2AStub,
+    a2a_agents,
+    load_a2a_sdk,
+)
+from spineagent.protocol.mcp.seam import (
+    McpClient,
+    McpClientTool,
+    McpServer,
+    McpTool,
+    OfflineMcpStub,
+    load_mcp_sdk,
+    mcp_clients,
+)
+from spineagent.tools.function_tool import FunctionTool, function_tool
+from spineagent.tools.tool import CalcTool, EchoTool, Tool, ToolResult, tool_registry
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # agent
+    "Agent",
+    "AgentResult",
+    "LlmAgent",
+    "FunctionAgent",
+    "ToolUsingAgent",
+    "AgentTool",
+    "FunctionCallingAgent",
+    # tool-policy 缝(会用工具的 agent 的「大脑」)
+    "ToolPolicy",
+    "ToolCall",
+    "Finish",
+    "Action",
+    "Observation",
+    "SyntaxToolPolicy",
+    "tool_policies",
+    # tools
+    "Tool",
+    "ToolResult",
+    "EchoTool",
+    "CalcTool",
+    "tool_registry",
+    "FunctionTool",
+    "function_tool",
+    # orchestration
+    "Coordinator",
+    "ChainAgent",
+    # llm provider 适配器(挂在 corespine LLMProvider 缝后面;输出统一 OpenAI ChatCompletion)
+    "AnthropicProvider",
+    "OpenAICompatProvider",
+    "CohereProvider",
+    "GeminiProvider",
+    "BedrockConverseProvider",
+    "llm_providers",
+    "load_anthropic_sdk",
+    "load_openai_sdk",
+    "load_cohere_sdk",
+    "load_gemini_sdk",
+    "load_boto3_sdk",
+    # protocol: mcp
+    "McpClient",
+    "McpServer",
+    "McpTool",
+    "McpClientTool",
+    "OfflineMcpStub",
+    "mcp_clients",
+    "load_mcp_sdk",
+    # protocol: a2a
+    "A2AAgent",
+    "A2ATask",
+    "A2AResult",
+    "A2AAgentAdapter",
+    "OfflineA2AStub",
+    "a2a_agents",
+    "load_a2a_sdk",
+    # conformance (本包绑定的不变量)
+    "AGENT_INVARIANTS",
+    "TOOL_INVARIANTS",
+    "POLICY_INVARIANTS",
+    "__version__",
+]

spineagent/agent/__init__.py

@@ -0,0 +1 @@
+"""spineagent.agent —— Agent 协议 + 最小默认实现(LlmAgent / FunctionAgent)。"""

spineagent/agent/agent.py

@@ -0,0 +1,122 @@
+"""agent 缝:Agent 协议 + 最小默认实现(单步执行)。
+
+家族缝的元模式:Protocol + 离线确定性默认 + 隐私安全 trace。Agent 是 spineagent 最小
+的执行单元——给一个任务,跑【一步】拿回结果。两个默认实现都离线可跑、零网络:
+
+  - LlmAgent —— 用一个 corespine LLMProvider 跑单步(离线用 MockProvider,确定性、可复现);
+  - FunctionAgent —— 把一个纯函数 (task->text) 包成 Agent(无需 LLM,做测试/编排的轻量节点)。
+
+隐私约定:step 可选接收一个 corespine TraceSink,实现只允许往里记【元数据】(agent 名、
+长度、token 数),【绝不】记任务/输出正文——由 InProcessPrivacyTraceSink「构造即保证」,
+本包再用 conformance 把这条不变量绑死(见 spineagent/conformance.py)。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from corespine.llm.provider import LLMProvider
+from corespine.observability.trace import TraceSink
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    """一次 agent 步的结果:产出文本 + 来源 agent 名(provenance)+ 可选 token 用量 / 错误。
+
+    error 仅在【编排层弹性模式】下捕获 agent.step 异常时填充——归一为家族统一的可序列化错误
+    dict(corespine.errors.error_to_dict:含 code / retryable / context)。正常成功路径 error 为
+    None;agent.step 自身的契约仍是「成功产出非空、失败抛异常」,捕获与否是 Coordinator 的策略。
+    """
+
+    agent: str
+    output: str
+    usage: dict[str, int] | None = None
+    error: dict[str, object] | None = None
+
+    @property
+    def ok(self) -> bool:
+        """这步是否成功(未捕获到错误)。"""
+        return self.error is None
+
+
+@runtime_checkable
+class Agent(Protocol):
+    """agent 协议:有名字;给一个任务,跑【一步】拿回结果。
+
+    step 可选接收一个 TraceSink:实现只允许往里记元数据(code/计数/耗时),绝不记任务/
+    输出正文——隐私 by construction,由 corespine 的 InProcessPrivacyTraceSink 兜底。
+    """
+
+    name: str
+
+    def step(self, task: str, *, trace: TraceSink | None = None) -> AgentResult: ...
+
+
+class LlmAgent:
+    """最小默认 agent:用一个 corespine LLMProvider 跑单步(离线用 MockProvider)。"""
+
+    def __init__(self, name: str, provider: LLMProvider, *, system: str = "") -> None:
+        self._name = name
+        self._provider = provider
+        self._system = system
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def step(self, task: str, *, trace: TraceSink | None = None) -> AgentResult:
+        messages: list[dict[str, str]] = [{"role": "user", "content": task}]
+        if self._system:
+            messages.insert(0, {"role": "system", "content": self._system})
+        completion = self._provider.chat(messages)
+        message = completion.choices[0].message
+        usage = (
+            {
+                "prompt_tokens": completion.usage.prompt_tokens,
+                "completion_tokens": completion.usage.completion_tokens,
+                "total_tokens": completion.usage.total_tokens,
+            }
+            if completion.usage is not None
+            else None
+        )
+        result = AgentResult(agent=self._name, output=message.content or "", usage=usage)
+        _emit_step(trace, self._name, task, result)
+        return result
+
+
+class FunctionAgent:
+    """最小确定性 agent:把一个纯函数 (task->text) 包成 Agent(离线/测试/编排用,无需 LLM)。"""
+
+    def __init__(self, name: str, fn: Callable[[str], str]) -> None:
+        self._name = name
+        self._fn = fn
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def step(self, task: str, *, trace: TraceSink | None = None) -> AgentResult:
+        result = AgentResult(agent=self._name, output=self._fn(task))
+        _emit_step(trace, self._name, task, result)
+        return result
+
+
+def _emit_step(
+    trace: TraceSink | None, name: str, task: str, result: AgentResult
+) -> None:
+    """记一条隐私安全的步级 trace:只记 agent 名 + 长度 + token 数,绝不记正文。"""
+    if trace is None:
+        return
+    usage = result.usage or {}
+    # trace 字段名沿用 input/output_tokens(隐私元数据词表);取值兼容 OpenAI usage 的 prompt/
+    # completion_tokens 与旧式 input/output_tokens 两种键。
+    trace.emit(
+        "agent_step",
+        agent=name,
+        task_chars=len(task),
+        output_chars=len(result.output),
+        input_tokens=usage.get("prompt_tokens", usage.get("input_tokens", 0)),
+        output_tokens=usage.get("completion_tokens", usage.get("output_tokens", 0)),
+    )

spineagent/agent/as_tool.py

@@ -0,0 +1,30 @@
+"""把一个 Agent 暴露成 Tool:让一个 agent 把另一个 agent 当工具调用(分层 / 督导式多 agent)。
+
+AgentTool 是把现有原语组合出【分层多 agent】的关键一块:一个督导 agent(ToolUsingAgent)通过
+工具调用把子任务派给专精的子 agent——子 agent 也可以自己再用工具、再带子 agent,层层嵌套。
+它与 McpClientTool(外部 MCP 工具 → Tool)、A2AAgentAdapter(远端 A2A agent → Agent)构成完整
+的桥接三角:本地 agent → Tool。
+
+run(arg) 即对子 agent 跑一步、取其输出包成带 provenance 的 ToolResult(tool = 工具名,默认取
+子 agent 名,可溯源到产出它的子 agent)。最薄桥接:只搬运文本(子 agent 的 usage / error 不
+透传);子 agent 抛异常照常上抛,与其它 Tool 一致——错误处理归编排层 / 调用方(见 Coordinator
+弹性容错)。Tool 协议的 run 无 trace 形参,故 AgentTool 自身不发 trace,外层 agent 循环会为这次
+工具调用发一条隐私安全的 tool_step(见 agent/tool_using.py)。
+"""
+
+from __future__ import annotations
+
+from spineagent.agent.agent import Agent
+from spineagent.tools.tool import ToolResult
+
+
+class AgentTool:
+    """跨原语适配器:把一个 Agent 桥成 Tool(实现 Tool 协议),用于分层 / 督导式多 agent。"""
+
+    def __init__(self, agent: Agent, *, name: str | None = None) -> None:
+        self._agent = agent
+        self.name = name or agent.name
+
+    def run(self, arg: str) -> ToolResult:
+        result = self._agent.step(arg)
+        return ToolResult(tool=self.name, output=result.output)

spineagent/agent/function_calling.py

@@ -0,0 +1,129 @@
+"""真 function-calling 的 agent:用一个 chat 模型的【原生工具调用】跑多步循环。
+
+与离线确定性的 ToolUsingAgent(SyntaxToolPolicy 按语法路由)不同,FunctionCallingAgent 让【真 LLM】
+自己决定调哪个工具:把 FunctionTool 的 schema 喂给 model.chat(tools=...),模型回 tool_calls →
+按名执行工具 → 把结果以 OpenAI tool 角色消息喂回 → 再 chat,直到模型不再要工具(出文本)或触顶
+max_steps。它实现 Agent 协议,故可直接进 Coordinator / 被 AgentTool 当工具 / 套进 ChainAgent。
+
+对外只认 corespine 的 OpenAI-canonical chat 缝(ChatCompletion + OpenAI message dicts),所以底层换
+任意 provider(OpenAI 兼容 / Anthropic / Gemini / Bedrock / Cohere)都不改这里一行——「统一 invoke」。
+离线默认 MockProvider 不回 tool_calls,故它直接出文本(诚实:离线不假装会 function-calling)。
+
+隐私:每步发 tool_step(agent / 步序 / 工具名 / 入参长度 / 输出长度)、收尾发 agent_finish、触顶发
+agent_step_limit——只记 code / 计数,绝不记任务 / 参数 / 输出正文。
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any
+
+from corespine.llm.provider import LLMProvider
+from corespine.observability.trace import TraceSink
+
+from spineagent.agent.agent import AgentResult
+from spineagent.tools.function_tool import FunctionTool
+
+# 触顶 max_steps 仍未出最终文本时的兜底文案(保证产出非空)。
+_NO_OUTPUT = "(reached max_steps without a final answer)"
+
+
+class FunctionCallingAgent:
+    """用真 LLM 的原生 function-calling 在单次 step() 内多步调用工具的 agent(实现 Agent 协议)。"""
+
+    def __init__(
+        self,
+        name: str,
+        model: LLMProvider,
+        tools: Iterable[FunctionTool],
+        *,
+        system: str = "",
+        max_steps: int = 8,
+    ) -> None:
+        self._name = name
+        self._model = model
+        self._tools = {tool.name: tool for tool in tools}
+        self._system = system
+        self._max_steps = max_steps
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def step(self, task: str, *, trace: TraceSink | None = None) -> AgentResult:
+        messages: list[dict[str, Any]] = [{"role": "user", "content": task}]
+        if self._system:
+            messages.insert(0, {"role": "system", "content": self._system})
+        schemas = [tool.schema() for tool in self._tools.values()] or None
+        last_usage: dict[str, int] | None = None
+        for index in range(self._max_steps):
+            result = self._model.chat(messages, tools=schemas)
+            last_usage = _usage_dict(result.usage)
+            message = result.choices[0].message
+            tool_calls = message.tool_calls or ()
+            if not tool_calls:
+                _emit_finish(trace, self._name, index, message.content or "")
+                return AgentResult(self._name, message.content or "", usage=last_usage)
+            # 把这一轮的 assistant(带 tool_calls)按 OpenAI 形状追加进对话历史。
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": message.content,
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {"name": tc.function.name, "arguments": tc.function.arguments},
+                        }
+                        for tc in tool_calls
+                    ],
+                }
+            )
+            # 逐个执行工具,把结果以 tool 角色消息喂回(tool_call_id 对齐)。
+            for tc in tool_calls:
+                tool = self._tools.get(tc.function.name)
+                arguments = tc.function.arguments or "{}"
+                if tool is None:
+                    output = f"error: unknown tool {tc.function.name!r}"
+                else:
+                    output = tool.invoke(json.loads(arguments))
+                messages.append({"role": "tool", "tool_call_id": tc.id, "content": output})
+                _emit_tool_step(trace, self._name, index, tc.function.name, arguments, output)
+        # 触顶 max_steps 仍在要工具:强制收尾(兜底非空)。
+        _emit_step_limit(trace, self._name, self._max_steps)
+        _emit_finish(trace, self._name, self._max_steps, _NO_OUTPUT)
+        return AgentResult(self._name, _NO_OUTPUT, usage=last_usage)
+
+
+def _usage_dict(usage: Any) -> dict[str, int] | None:
+    if usage is None:
+        return None
+    return {
+        "prompt_tokens": usage.prompt_tokens,
+        "completion_tokens": usage.completion_tokens,
+        "total_tokens": usage.total_tokens,
+    }
+
+
+def _emit_tool_step(
+    trace: TraceSink | None, name: str, step: int, tool: str, arguments: str, output: str
+) -> None:
+    """隐私安全步级 trace:agent 名 / 步序 / 工具名 / 入参与输出长度,绝不记正文。"""
+    if trace is None:
+        return
+    trace.emit(
+        "tool_step", agent=name, step=step, tool=tool, arg_chars=len(arguments), output_chars=len(output)
+    )
+
+
+def _emit_finish(trace: TraceSink | None, name: str, steps: int, answer: str) -> None:
+    if trace is None:
+        return
+    trace.emit("agent_finish", agent=name, steps=steps, answer_chars=len(answer))
+
+
+def _emit_step_limit(trace: TraceSink | None, name: str, max_steps: int) -> None:
+    if trace is None:
+        return
+    trace.emit("agent_step_limit", agent=name, max_steps=max_steps)

spineagent/agent/policy.py

@@ -0,0 +1,121 @@
+"""tool-policy 缝:ToolPolicy 协议 + 离线确定性默认(决定 agent 下一步调哪个工具)。
+
+家族缝的元模式(同 mcp / a2a 缝):Protocol + 离线确定性默认 + Registry 工厂 + 参数化
+conformance。一个 ToolPolicy 是「会用工具的 agent」的大脑:给一个任务、当前可用的工具名
+集合、以及已执行步的观测历史,定下一个动作——【调某个工具】或【收尾给最终答案】。
+
+【离线默认为何不靠 LLM 推理(诚实性取舍)】corespine 的 MockProvider 只做「回声 + sha256
+指纹」,对任何 prompt 都吐 `[mock:<hex>] <prompt>`,绝不可能推理出 `{tool: calc, arg: 1+1}`。
+任何「解析 LLM 输出找 tool call」的默认实现,在离线下要么永远解析失败、空转到 max_steps,
+要么把 mock 输出硬塞进解析器自欺。所以离线默认【绝不依赖 LLM 选工具】——正如 MockProvider
+用回声诚实地「不假装生成内容」,SyntaxToolPolicy 把「工具调用意图」显式化为任务文本里的
+确定性语法,纯函数解析。它是这条缝的【确定性参照实现】;真实推理式 policy(走 corespine
+真 provider 解析 function-calling)应注册进 tool_policies 的 'llm' 位,与 mcp/a2a 的
+offline/real 二分完全同构。
+
+decide 是【无状态纯函数】:循环状态全由入参 history 携带,同一 (task, tools, history) 恒定
+产出同一 Action——可断言、可复现、零网络,也便于将来直接映射到一次 stateless completion。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, TypeAlias, runtime_checkable
+
+from corespine.errors import SeamError
+from corespine.seam.registry import Registry
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """决定:调一个工具(tool 名 + 传给它的参数)。arg 中字面量 $prev 由 agent 侧替换为上一步观测。"""
+
+    tool: str
+    arg: str
+
+
+@dataclass(frozen=True)
+class Finish:
+    """决定:收尾,给出最终答案(保证非空)。"""
+
+    answer: str
+
+
+# 一个决策动作:调工具,或收尾。isinstance 分发(PEP 604 联合)。
+Action: TypeAlias = ToolCall | Finish
+
+
+@dataclass(frozen=True)
+class Observation:
+    """一步执行的观测:产出它的工具名 + 实际入参 + 输出。喂回循环,供 $prev 链式消费与收尾拼接。"""
+
+    tool: str
+    arg: str
+    output: str
+
+
+@runtime_checkable
+class ToolPolicy(Protocol):
+    """tool-policy 协议:给 task + 可用工具名集 + 历史观测,决定下一个动作(调工具 / 收尾)。"""
+
+    def decide(
+        self, task: str, *, tools: tuple[str, ...], history: tuple[Observation, ...]
+    ) -> Action: ...
+
+
+def _parse_instruction(line: str, tools: tuple[str, ...]) -> tuple[str, str] | None:
+    """把一行解析成 (工具名, 参数):形如 `<tool>: <arg>` 且工具名在 tools 内才算指令,否则视为正文。"""
+    if ":" not in line:
+        return None
+    name, _, arg = line.partition(":")
+    name = name.strip()
+    if name in tools:
+        return name, arg.strip()
+    return None
+
+
+class SyntaxToolPolicy:
+    """离线确定性默认:按任务文本里的 `<tool>: <arg>` 显式语法 + 工具名集合,确定性路由工具调用。
+
+    无状态纯函数:游标 = len(history) 表示「已执行到第几条工具指令」。第 cursor 条工具指令尚存
+    则返回 ToolCall(该行工具名, 该行参数);工具指令耗尽则返回 Finish(把非指令正文行 + 最后一步
+    观测按固定模板拼成最终答案,保证非空)。同一输入恒定同一输出。
+    """
+
+    def decide(
+        self, task: str, *, tools: tuple[str, ...], history: tuple[Observation, ...]
+    ) -> Action:
+        # 单遍把每行分流:能解析成工具指令的入 instructions,其余非空行入 prose 正文。
+        instructions: list[tuple[str, str]] = []
+        prose: list[str] = []
+        for line in task.splitlines():
+            parsed = _parse_instruction(line, tools)
+            if parsed is not None:
+                instructions.append(parsed)
+            elif stripped := line.strip():
+                prose.append(stripped)
+        cursor = len(history)
+        if cursor < len(instructions):
+            name, arg = instructions[cursor]
+            return ToolCall(tool=name, arg=arg)
+        # 工具指令耗尽 -> 收尾:非指令正文行 + 最后一步观测输出,拼成非空答案。
+        parts = prose + ([history[-1].output] if history else [])
+        answer = "\n".join(p for p in parts if p) or task.strip() or "(no output)"
+        return Finish(answer=answer)
+
+
+def _make_llm_policy(**kwargs: Any) -> ToolPolicy:
+    # 真实推理式 policy 的占位(与 mcp/a2a 的 'real' 同构)。不同点:LLM policy 走 corespine
+    # LLMProvider 真后端,无网络 SDK 可延迟 import,故直接给「缝未接入」的明确报错。
+    # 用家族统一 SeamError(code="seam.unknown"):任何「缝槽存在但真实实现未接入」都同一形状。
+    raise SeamError(
+        "真实 LLM 推理式 ToolPolicy 留待接入:应走 corespine LLMProvider 真后端解析 "
+        "function-calling / 工具调用,并注册进 tool_policies 的 'llm' 位;"
+        "本壳只提供缝 + 离线确定性默认 SyntaxToolPolicy。"
+    )
+
+
+# 缝注册表:一个 spec 选实现(默认 offline 离线确定性默认;llm 走真实推理式接入)。
+tool_policies: Registry[ToolPolicy] = Registry("tool_policy")
+tool_policies.register("offline", lambda **kw: SyntaxToolPolicy(**kw))
+tool_policies.register("llm", _make_llm_policy)

spineagent/agent/tool_using.py

@@ -0,0 +1,107 @@
+"""会用工具的多步 agent:在一次 step() 内跑「决策→调工具→喂回观测→再决策」的循环。
+
+ToolUsingAgent 实现现有 Agent 协议(name + step),因此【零改 Coordinator】即可进顺序 / 并行
+编排。一次 step() 内:用一个 ToolPolicy 决定下一个动作——调某工具则按名取 Tool 执行、把观测
+追加进历史(供下一步 $prev 链式消费)、发一条隐私安全步级 trace;收尾则返回最终 AgentResult。
+
+max_steps 守卫:其语义是【最多调用多少次工具】(收尾决策本身不占步预算)。已用满 max_steps
+次工具调用后,policy 若还想再调工具,则强制收尾——即便 policy 异常永不返回 Finish,也绝不
+死循环(history 每步单调增长,必在 max_steps 内触顶)。
+
+$prev:工具参数里字面量 `$prev` 在【执行前】替换为上一步观测的输出(history 为空时替换为空
+串),让「把观测喂回循环」名副其实。替换只发生在内存里,trace 只记其长度,绝不写进正文。
+注意:若【首步】即引用 $prev(尚无上一步输出),替换为空串后,余下参数能否被工具处理由工具
+自身决定;工具若拒绝该参数(如 CalcTool 对空串抛错),异常照常上抛——错误处理 / 重试不在本
+增量范围(rule of three),调用方自行处理。
+
+隐私 trace:每步发 tool_step(agent / 步序 / 工具名 / 入参长度 / 输出长度),收尾发 agent_finish
+(agent / 总步数 / 答案长度),触顶发 agent_step_limit——字段全为 code / 计数 / 序号,键名全程
+规避 corespine FORBIDDEN_KEYS,绝不携带 task / arg / output / answer 正文。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from corespine.observability.trace import TraceSink
+
+from spineagent.agent.agent import AgentResult
+from spineagent.agent.policy import Finish, Observation, ToolPolicy
+from spineagent.tools.tool import Tool
+
+# 触顶 max_steps 又无任何观测可作答时的固定兜底文案(保证产出非空)。
+_NO_OUTPUT = "(reached max_steps without finishing)"
+
+
+class ToolUsingAgent:
+    """用一个 ToolPolicy 驱动、在单次 step() 内多步调用工具的 agent(实现 Agent 协议)。"""
+
+    def __init__(
+        self,
+        name: str,
+        policy: ToolPolicy,
+        tools: Iterable[Tool],
+        *,
+        max_steps: int = 8,
+    ) -> None:
+        self._name = name
+        self._policy = policy
+        self._tools = {tool.name: tool for tool in tools}
+        # 工具名集合(传给 policy 用以避免幻觉一个不存在的工具);顺序 = 插入序。
+        self._tool_names = tuple(self._tools)
+        self._max_steps = max_steps
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def step(self, task: str, *, trace: TraceSink | None = None) -> AgentResult:
+        history: list[Observation] = []
+        while True:
+            action = self._policy.decide(
+                task, tools=self._tool_names, history=tuple(history)
+            )
+            if isinstance(action, Finish):
+                _emit_finish(trace, self._name, len(history), action.answer)
+                return AgentResult(agent=self._name, output=action.answer)
+            # ToolCall:已用满 max_steps 次工具调用,policy 还想再调 -> 触顶强制收尾。
+            if len(history) >= self._max_steps:
+                answer = (history[-1].output if history else "") or _NO_OUTPUT
+                _emit_step_limit(trace, self._name, self._max_steps)
+                _emit_finish(trace, self._name, len(history), answer)
+                return AgentResult(agent=self._name, output=answer)
+            # 把 $prev 替换为上一步观测输出后执行该工具,观测追加进历史。
+            arg = action.arg.replace("$prev", history[-1].output if history else "")
+            result = self._tools[action.tool].run(arg)
+            history.append(Observation(tool=action.tool, arg=arg, output=result.output))
+            _emit_tool_step(trace, self._name, len(history) - 1, action.tool, arg, result.output)
+
+
+def _emit_tool_step(
+    trace: TraceSink | None, name: str, step: int, tool: str, arg: str, output: str
+) -> None:
+    """记一条隐私安全的步级 trace:只记 agent 名 / 步序 / 工具名 / 入参与输出长度,绝不记正文。"""
+    if trace is None:
+        return
+    trace.emit(
+        "tool_step",
+        agent=name,
+        step=step,
+        tool=tool,
+        arg_chars=len(arg),
+        output_chars=len(output),
+    )
+
+
+def _emit_finish(trace: TraceSink | None, name: str, steps: int, answer: str) -> None:
+    """记收尾 trace:agent 名 / 总步数 / 答案长度(answer_chars,绝不用 answer 键携带正文)。"""
+    if trace is None:
+        return
+    trace.emit("agent_finish", agent=name, steps=steps, answer_chars=len(answer))
+
+
+def _emit_step_limit(trace: TraceSink | None, name: str, max_steps: int) -> None:
+    """记触顶 trace:便于排障「为何提前收尾」。"""
+    if trace is None:
+        return
+    trace.emit("agent_step_limit", agent=name, max_steps=max_steps)