106 lines
3.9 KiB
Python
106 lines
3.9 KiB
Python
"""spawn 工具：用于把任务委派给后台 agent。"""
|
||
|
||
from typing import TYPE_CHECKING, Any
|
||
|
||
from nanobot.agent.tools.base import Tool
|
||
|
||
if TYPE_CHECKING:
|
||
from nanobot.agent.delegation import DelegationManager
|
||
|
||
|
||
class SpawnTool(Tool):
|
||
"""
|
||
后台委派工具。
|
||
|
||
作用：
|
||
1. 把耗时/可并行的任务委派给 DelegationManager；
|
||
2. 目标可以是本地 agent、A2A 远端 agent 或 agent group；
|
||
3. 后台任务异步执行，不阻塞当前对话回合。
|
||
"""
|
||
|
||
def __init__(self, manager: "DelegationManager"):
|
||
# manager 负责真正创建 asyncio 后台任务并管理生命周期。
|
||
self._manager = manager
|
||
# 默认来源会话（CLI 直连场景）。实际会在每轮由 loop._set_tool_context 覆盖。
|
||
self._origin_channel = "cli"
|
||
self._origin_chat_id = "direct"
|
||
self._announce_via_bus = True
|
||
|
||
def set_context(self, channel: str, chat_id: str, announce_via_bus: bool = True) -> None:
|
||
"""设置后台委派结果回传的目标会话。"""
|
||
# 委派任务完成后并不会直接给用户发消息，
|
||
# 而是把结果发回这里记录的 origin（channel/chat_id）对应会话。
|
||
self._origin_channel = channel
|
||
self._origin_chat_id = chat_id
|
||
self._announce_via_bus = announce_via_bus
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
# 暴露给 LLM 的工具名；模型会用这个名字发起 function call。
|
||
return "spawn"
|
||
|
||
@property
|
||
def description(self) -> str:
|
||
# 给模型看的能力描述，强调“后台执行 + 完成后回报”语义。
|
||
return (
|
||
"Delegate a task to a background agent. "
|
||
"Use this for complex or time-consuming work that can run independently. "
|
||
"You can target a specific agent, a group of agents, or let the system choose. "
|
||
"The delegated agent(s) will report back when done."
|
||
)
|
||
|
||
@property
|
||
def parameters(self) -> dict[str, Any]:
|
||
# OpenAI function schema：定义模型可传入的参数结构。
|
||
return {
|
||
"type": "object",
|
||
"properties": {
|
||
"task": {
|
||
"type": "string",
|
||
"description": "The task for the delegated agent to complete",
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"description": "Optional short label for the task (for display)",
|
||
},
|
||
"target": {
|
||
"type": "string",
|
||
"description": "Optional agent ID or name for a single target",
|
||
},
|
||
"targets": {
|
||
"type": "array",
|
||
"items": {"type": "string"},
|
||
"description": "Optional list of agent IDs/names for a group task",
|
||
},
|
||
"strategy": {
|
||
"type": "string",
|
||
"enum": ["auto", "local", "plugin", "a2a", "group"],
|
||
"description": "Routing strategy. Default is auto.",
|
||
},
|
||
},
|
||
"required": ["task"],
|
||
}
|
||
|
||
async def execute(
|
||
self,
|
||
task: str,
|
||
label: str | None = None,
|
||
target: str | None = None,
|
||
targets: list[str] | None = None,
|
||
strategy: str = "auto",
|
||
**kwargs: Any,
|
||
) -> str:
|
||
"""创建并启动一个后台委派任务。"""
|
||
# 这里仅负责转发请求，不在本工具内执行实际任务逻辑。
|
||
# 返回值是“已启动”状态文本，真正结果稍后通过主消息总线回传。
|
||
return await self._manager.dispatch(
|
||
task=task,
|
||
label=label,
|
||
target=target,
|
||
targets=targets,
|
||
strategy=strategy,
|
||
origin_channel=self._origin_channel,
|
||
origin_chat_id=self._origin_chat_id,
|
||
announce_via_bus=self._announce_via_bus,
|
||
)
|