初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

@@ -0,0 +1,11 @@
from .tools import get_available_tools
__all__ = ["get_available_tools", "skill_manage_tool"]
def __getattr__(name: str):
if name == "skill_manage_tool":
from .skill_manage_tool import skill_manage_tool
return skill_manage_tool
raise AttributeError(name)
@@ -0,0 +1,23 @@
from .agent_orchestration_tool import agent_orchestration_tool
from .clarification_tool import ask_clarification_tool
from .memory_tool import memory_tool
from .present_file_tool import present_file_tool
from .scheduled_task_tool import scheduled_task_tool
from .setup_agent_tool import setup_agent
from .setup_report_structure_tool import setup_report_structure
from .setup_writing_tool import setup_writing
from .task_tool import task_tool
from .view_image_tool import view_image_tool
__all__ = [
"setup_agent",
"setup_report_structure",
"setup_writing",
"present_file_tool",
"ask_clarification_tool",
"agent_orchestration_tool",
"memory_tool",
"scheduled_task_tool",
"view_image_tool",
"task_tool",
]
@@ -0,0 +1,46 @@
"""Placeholder tool that lets the roundtable leader agent dispatch sub-agents.
Background
----------
The multi-agent ``/api/multi-agent/run/stream`` endpoint (``app.gateway.routers.multi_agent``)
drives a *leader* agent whose only job is to delegate work to seat-specific sub-agents.
Its SOUL.md tells the model to "use the agent_orchestration skill, passing agent_name
and task". With no real tool registered under that name, the model used to emit
``{"name": "agent_orchestration", "args": {"agent_name": ..., "task": ...}}`` calls
that the runtime rejected with "agent_orchestration is not a valid tool", driving it
into an unproductive retry loop (a single leader call could exceed 10 000 SSE frames).
This module exposes a no-op tool with the exact signature the leader naturally
emits. The actual dispatch is handled by ``SkillStopMiddleware`` which intercepts
the call, halts the run, and lets ``multi_agent.py`` parse the AIMessage's
``tool_calls`` to extract ``(agent_name, task)`` pairs for the frontend.
"""
from langchain.tools import tool
@tool("agent_orchestration", parse_docstring=True)
def agent_orchestration_tool(agent_name: str, task: str) -> str:
"""Delegate a task to a named sub-agent in the multi-agent roundtable.
Use this tool ONLY when you are the roundtable coordinator and need to
dispatch work to one of the configured seat agents. Each call delegates
ONE task to ONE agent. Emit multiple calls in the same turn to dispatch
several seats in a single round of the discussion.
The call is intercepted by the runtime — you do not get a real result
back synchronously. The orchestrator will collect every dispatched
``(agent_name, task)`` pair, run the corresponding sub-agents, then
re-prompt you with a synthesis instruction once they finish.
Args:
agent_name: Name of the sub-agent to dispatch. MUST exactly match one of
the names listed in your SOUL prompt's ``可调度智能体`` section.
task: The instruction to hand to that sub-agent. Be specific — the
sub-agent only sees this string (plus its own SOUL prompt), not the
broader conversation context.
"""
# Real handling is in SkillStopMiddleware + the multi_agent router. This
# body only runs as a fallback if the middleware is not configured; it
# returns a placeholder so the model does not see a "not a valid tool" error.
return f"dispatched:{agent_name}"
@@ -0,0 +1,225 @@
"""Interactive browser action tool backed by the user's Chrome extension.
Unlike ``browser_fetch_page`` (a one-shot read), this tool drives an
*observe -> act* loop on a live page the extension keeps open:
1. The model calls ``browser_act`` with an action (navigate/click/type/...).
2. The extension performs the action on the session tab, then re-scans the page
and returns an *observation*: the final URL/title, an indexed list of
interactive elements, and the visible page text.
3. The model reads the observation, picks the next element by its index, and
calls ``browser_act`` again with the same ``session_id``.
The element ``index`` values are only valid for the most recent observation of a
session; always act on indices from the latest result.
"""
from __future__ import annotations
from typing import Any
from urllib.parse import urlparse
from uuid import uuid4
from langchain.tools import tool
from deerflow.browser_context.tasks import create_browser_task, wait_for_browser_task_result
from deerflow.config import get_app_config
from deerflow.config.browser_context_config import BrowserContextConfig
from deerflow.runtime.user_context import get_effective_user_id
_ACTIONS = {"navigate", "click", "type", "scroll", "wait", "extract", "observe", "close"}
_NEEDS_INDEX = {"click", "type"}
def _settings() -> BrowserContextConfig:
value = getattr(get_app_config(), "browser_context", None)
if isinstance(value, BrowserContextConfig):
return value
if isinstance(value, dict):
return BrowserContextConfig.model_validate(value)
return BrowserContextConfig()
def _validate_url(raw_url: str) -> str | None:
url = (raw_url or "").strip()
parsed = urlparse(url)
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
return None
return url
def _format_elements(elements: list[dict[str, Any]] | None) -> str:
if not elements:
return "(no interactive elements detected)"
lines: list[str] = []
for el in elements:
idx = el.get("index")
tag = str(el.get("tag") or "?")
el_type = str(el.get("type") or "").strip()
label = str(el.get("label") or "").strip().replace("\n", " ")
if len(label) > 120:
label = label[:120] + "…"
descriptor = f"{tag}" + (f"[{el_type}]" if el_type else "")
extra = ""
if el.get("value"):
value = str(el["value"]).strip().replace("\n", " ")
extra = f' value="{value[:60]}"'
lines.append(f"[{idx}] {descriptor} \"{label}\"{extra}".rstrip())
return "\n".join(lines)
def _format_observation(action: str, observation: dict[str, Any] | None, session_id: str, settings: BrowserContextConfig) -> str:
observation = observation or {}
status = str(observation.get("action_status") or "ok")
message = str(observation.get("message") or "").strip()
url = str(observation.get("url") or "").strip() or "(unknown)"
title = str(observation.get("title") or "").strip() or "(untitled)"
elements = observation.get("elements") if isinstance(observation.get("elements"), list) else []
text = str(observation.get("text") or "").strip()
text_limit = max(500, int(settings.observation_text_max_chars))
text_truncated = len(text) > text_limit
if text_truncated:
text = text[:text_limit]
parts = [
f"Browser session: {session_id}",
f"Last action: {action} -> {status}",
]
if message:
parts.append(f"Note: {message}")
parts.extend(
[
f"URL: {url}",
f"Title: {title}",
"",
"Interactive elements (use the [index] with click/type):",
_format_elements(elements),
"",
"Page text:",
text or "(empty page text)",
]
)
if text_truncated:
parts.append("\n[Page text truncated by browser_context.observation_text_max_chars]")
parts.append(
"\nNext step: call browser_act again with this session_id and the index of the element to act on. "
"When the task is finished, call browser_act with action=\"close\" to release the tab."
)
return "\n".join(parts)
@tool("browser_act", parse_docstring=True)
async def browser_act_tool(
action: str,
session_id: str = "",
url: str = "",
index: int = -1,
text: str = "",
submit: bool = False,
wait_for: str = "",
wait_seconds: int = 0,
) -> str:
"""Drive an interactive observe/act loop on a page in the user's Chrome browser.
Use this to operate a real web page on the user's behalf — log in, fill forms,
click through navigation, and read pages that need the user's session or local
network. Start every task with ``action="navigate"`` and a URL to open a tab
and get the first observation, then keep calling this tool with the same
``session_id``, choosing elements by the ``index`` shown in the observation.
Call ``action="close"`` when done to free the tab.
Args:
action: One of navigate, click, type, scroll, wait, extract, observe, close.
session_id: Session id from a previous observation. Leave empty to start a new session (requires navigate + url).
url: Target http(s) URL. Required for navigate (and to start a new session).
index: Index of the interactive element to act on, taken from the latest observation. Required for click and type.
text: Text to enter for the type action.
submit: For type, press Enter / submit the form after typing.
wait_for: For wait, a CSS selector to wait for before observing.
wait_seconds: Optional extra seconds to wait for this step's result. Zero uses the configured default.
"""
settings = _settings()
if not settings.enabled:
return "browser_act is disabled by config.yaml: browser_context.enabled is false."
if not settings.actions_enabled:
return "browser_act is disabled by config.yaml: browser_context.actions_enabled is false."
action = (action or "").strip().lower()
if action not in _ACTIONS:
return f"browser_act: unknown action {action!r}. Use one of: {', '.join(sorted(_ACTIONS))}."
session_id = (session_id or "").strip()
safe_url = _validate_url(url) if url else None
if action == "navigate" and safe_url is None:
return "browser_act navigate requires an exact http(s) URL, for example https://example.com/page."
if not session_id:
if action != "navigate":
return "browser_act: no session_id yet. Start with action=\"navigate\" and a url to open the page first."
session_id = uuid4().hex
if action in _NEEDS_INDEX and index < 0:
return f"browser_act {action} requires a non-negative element index from the latest observation."
if action == "type" and not text:
return "browser_act type requires the text to enter."
action_payload: dict[str, Any] = {"type": action}
if safe_url is not None:
action_payload["url"] = safe_url
if index >= 0:
action_payload["index"] = int(index)
if text:
action_payload["text"] = text
if submit:
action_payload["submit"] = True
if wait_for.strip():
action_payload["wait_for"] = wait_for.strip()[:300]
configured_timeout = max(5, int(settings.action_result_timeout_seconds))
requested_timeout = int(wait_seconds or configured_timeout)
timeout = min(max(5, requested_timeout), configured_timeout)
user_id = get_effective_user_id()
task = create_browser_task(
user_id=user_id,
url=safe_url or "",
instruction="",
kind="act",
session_id=session_id,
action=action_payload,
timeout_seconds=timeout + int(settings.task_lease_seconds),
max_content_chars=settings.max_content_chars,
metadata={"source": "browser_act_tool"},
)
completed = await wait_for_browser_task_result(
task_id=task["id"],
user_id=user_id,
timeout_seconds=timeout,
poll_interval_seconds=settings.task_poll_interval_seconds,
)
if completed is None:
return f"Browser task {task['id']} was not found after it was created."
status = completed.get("status")
if status == "error":
return f"browser_act session {session_id}: step failed: {completed.get('error') or 'unknown error'}"
if status == "expired":
return (
f"browser_act session {session_id}: the Chrome extension did not respond in time. "
"Check that Deer Web Clipper is installed, the same user is logged in, and task polling is enabled."
)
if status != "done":
return (
f"browser_act session {session_id}: step is still {status or 'pending'} after {timeout} seconds. "
"Keep the Deer Web Clipper extension running with task polling enabled, then try again."
)
if action == "close":
return f"browser_act session {session_id}: tab closed."
result = completed.get("result") or {}
observation = result.get("observation") if isinstance(result.get("observation"), dict) else None
return _format_observation(action, observation, session_id, settings)
@@ -0,0 +1,117 @@
"""Browser extension backed page fetch tool."""
from __future__ import annotations
from urllib.parse import urlparse
from langchain.tools import tool
from deerflow.browser_context.tasks import create_browser_task, wait_for_browser_task_result
from deerflow.config import get_app_config
from deerflow.config.browser_context_config import BrowserContextConfig
from deerflow.runtime.user_context import get_effective_user_id
def _settings() -> BrowserContextConfig:
value = getattr(get_app_config(), "browser_context", None)
if isinstance(value, BrowserContextConfig):
return value
if isinstance(value, dict):
return BrowserContextConfig.model_validate(value)
return BrowserContextConfig()
def _validate_url(raw_url: str) -> str | None:
url = (raw_url or "").strip()
parsed = urlparse(url)
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
return None
return url
@tool("browser_fetch_page", parse_docstring=True)
async def browser_fetch_page_tool(url: str, question: str = "", wait_seconds: int = 0) -> str:
"""Ask the user's paired Chrome extension to fetch a page and return visible page text.
Use this when the user explicitly asks to use the browser extension or asks
for data from a page that may require their browser session, login state, or
local network access. The URL must be an exact http(s) URL provided by the
user. If the user did not provide a URL, ask for the URL instead of guessing.
Args:
url: Exact http(s) URL to open in the user's Chrome browser.
question: Optional instruction describing what data the user wants from the page.
wait_seconds: Optional seconds to wait for the extension result. Zero uses the configured default.
"""
settings = _settings()
if not settings.enabled:
return "browser_fetch_page is disabled by config.yaml: browser_context.enabled is false."
safe_url = _validate_url(url)
if safe_url is None:
return "browser_fetch_page requires an exact http(s) URL, for example https://example.com/page."
configured_timeout = max(5, int(settings.task_result_timeout_seconds))
requested_timeout = int(wait_seconds or configured_timeout)
timeout = min(max(5, requested_timeout), configured_timeout)
user_id = get_effective_user_id()
task = create_browser_task(
user_id=user_id,
url=safe_url,
instruction=(question or "").strip(),
timeout_seconds=timeout + int(settings.task_lease_seconds),
max_content_chars=settings.max_content_chars,
metadata={"source": "browser_fetch_page_tool"},
)
completed = await wait_for_browser_task_result(
task_id=task["id"],
user_id=user_id,
timeout_seconds=timeout,
poll_interval_seconds=settings.task_poll_interval_seconds,
)
if completed is None:
return f"Browser task {task['id']} was not found after it was created."
status = completed.get("status")
if status == "error":
return f"Browser task {task['id']} failed: {completed.get('error') or 'unknown error'}"
if status == "expired":
return (
f"Browser task {task['id']} expired before the Chrome extension returned a result. "
"Check that Deer Web Clipper is installed, configured with the same access token, and task polling is enabled."
)
if status != "done":
return (
f"Browser task {task['id']} is still {status or 'pending'} after {timeout} seconds. "
"Keep the Deer Web Clipper extension running with task polling enabled, then try again."
)
result = completed.get("result") or {}
content = str(result.get("content") or "").strip()
tool_limit = max(1_000, int(settings.tool_result_max_chars))
tool_truncated = len(content) > tool_limit
if tool_truncated:
content = content[:tool_limit]
notes: list[str] = []
if result.get("truncated"):
notes.append("The browser capture was truncated by browser_context.max_content_chars.")
if tool_truncated:
notes.append("The tool response was truncated by browser_context.tool_result_max_chars.")
parts = [
"Browser page fetched through the user's Chrome extension.",
f"Task ID: {task['id']}",
f"Title: {result.get('title') or '(untitled)'}",
f"URL: {result.get('url') or safe_url}",
]
if question:
parts.extend(["", "Requested extraction:", question.strip()])
if notes:
parts.extend(["", "Notes:", "\n".join(f"- {note}" for note in notes)])
parts.extend(["", "Page content:", content or "(empty page text)"])
return "\n".join(parts)
@@ -0,0 +1,78 @@
from typing import Literal
from langchain.tools import tool
# ClarificationMiddleware owns the stop behaviour: it returns a Command that
# writes the ToolMessage and explicitly routes to END. ``return_direct=True``
# makes the prebuilt tool node short-circuit before that Command update is
# checkpointed in some LangGraph versions, leaving an assistant tool call
# without its matching ToolMessage. The next user reply then fails provider
# validation with "tool_calls must be followed by tool messages".
@tool("ask_clarification", parse_docstring=True, return_direct=False)
def ask_clarification_tool(
question: str,
clarification_type: Literal[
"missing_info",
"ambiguous_requirement",
"approach_choice",
"risk_confirmation",
"suggestion",
],
context: str | None = None,
options: list[str] | None = None,
allow_multiple: bool | None = None,
) -> str:
"""Ask the user for clarification when you need more information to proceed.
Use this tool when you encounter situations where you cannot proceed without user input:
- **Missing information**: Required details not provided (e.g., file paths, URLs, specific requirements)
- **Ambiguous requirements**: Multiple valid interpretations exist
- **Approach choices**: Several valid approaches exist and you need user preference
- **Risky operations**: Destructive actions that need explicit confirmation (e.g., deleting files, modifying production)
- **Suggestions**: You have a recommendation but want user approval before proceeding
The execution will be interrupted and the question will be presented to the user.
Wait for the user's response before continuing.
When to use ask_clarification:
- You need information that wasn't provided in the user's request
- The requirement can be interpreted in multiple ways
- Multiple valid implementation approaches exist
- You're about to perform a potentially dangerous operation
- You have a recommendation but need user approval
Batching multiple independent questions:
- **You CAN and SHOULD call ask_clarification multiple times in the same turn** when the user's
request leaves several **independent** aspects unclear (e.g. project type AND tech stack AND
deployment target). Emit one tool call per aspect — do NOT cram several unrelated questions
into one `question` string.
- The frontend automatically groups all clarification cards in one turn into a single submission,
so the user answers them together in one reply. You will then receive one combined user message
addressing every question in order.
- When the questions DEPEND on each other (the second only makes sense after the first is answered),
ask only the first one and wait for the reply before asking the next.
Best practices:
- One question per ask_clarification call — keep each `question` focused on a single decision.
- Be specific and clear in your question.
- Provide `options` (with concise labels) whenever there is a discrete set of reasonable choices.
- By default the UI is **single-select** (click an option to send). Pass `allow_multiple=True`
only when the user may legitimately pick several options together (e.g. multiple constraints).
- Don't make assumptions when clarification is needed.
- For risky operations, ALWAYS ask for confirmation.
- After calling this tool (or several in one turn), execution will be interrupted automatically.
Args:
question: The clarification question to ask the user. Focused on a single decision; be specific and clear.
clarification_type: The type of clarification needed (missing_info, ambiguous_requirement, approach_choice, risk_confirmation, suggestion).
context: Optional context explaining why clarification is needed. Helps the user understand the situation.
options: Optional list of choices. Present clear options for the user to choose from.
allow_multiple: When True, the UI allows multi-select plus a submit button. When False or
omitted, the UI is single-select and sends immediately on click (default).
"""
# This is a placeholder implementation
# The actual logic is handled by ClarificationMiddleware which intercepts this tool call
# and interrupts execution to present the question to the user
return "Clarification request processed by middleware"
@@ -0,0 +1,37 @@
"""ask_clarification 工具参数的共享解析(Harness + Gateway)。
圆桌 Step 1(``intent.py``)与 Step 2 总控(``multi_agent.py``)在 SSE 终态帧里
都会带上 ``allow_multiple``,供前端 ``resolveAllowMultiple`` 决定选项卡片是
「点击即发送(单选)」还是「多选 + 发送按钮」。
约定(与前端 ``roundtable-planning/lib/clarification.ts`` 一致):
- 模型**未传** ``allow_multiple`` 或传 ``null`` → **False**(单选);
- 仅当模型显式传 ``true`` 时才多选;
- 不再根据 ``clarification_type`` 推断多选(旧逻辑已移除)。
"""
from __future__ import annotations
def coerce_bool(value: object | None, *, default: bool) -> bool:
"""把 LLM tool args 里可能出现的 bool/数字/字符串统一成 bool。"""
if value is None:
return default
if isinstance(value, bool):
return value
if isinstance(value, (int, float)):
return bool(value)
if isinstance(value, str):
lowered = value.strip().lower()
if lowered in ("true", "1", "yes", "y", "on"):
return True
if lowered in ("false", "0", "no", "n", "off"):
return False
return bool(value)
def resolve_allow_multiple(args: dict) -> bool:
"""是否允许多选。仅 ``args["allow_multiple"]`` 显式为真时返回 True。"""
if "allow_multiple" in args and args["allow_multiple"] is not None:
return coerce_bool(args["allow_multiple"], default=False)
return False
@@ -0,0 +1,573 @@
"""写作模式的内联深度研究报告工具。
聊天输入框「写作模式」首轮(尚无 report.md 产物)在**交付时刻**(模型认为
对话已经聊得差不多、该出报告了)调用本工具:优先把**对话中已经产生的**
工具结果收割成研究资料池,内联运行 DeepResearchEngine(basic runner),按
「通用分析结构」大纲撰写 ``report.md``,直接写进**当前聊天线程**的沙箱
``outputs/`` 目录——前端画布 / 编辑 / 下载 / 续写全部沿用既有 artifacts 通道。
除「写 md」这一动作换成管线外,agent 的对话 / 检索 / 澄清行为一切照旧。
资料来源(收割池先按**当前主题**做词面相关度强过滤——旧课题的检索
结果不进报告):
- 一律用对话里已经产生的资料写(哪怕为空——basic runner 有领域知识兜底),
**不再**因条数不足打断用户,也**不再**在管线内部补检索。
需要检索时由 lead agent 用对话工具先搜,再调用本工具写文件。
报告管线继承聊天里选择的模型与思考开关(``context.model_name`` /
``thinking_enabled`` / ``thinking_force_disabled``,经 run config 白名单透
传),与「除写 md 外其他行为保持原样」一致;缺省回落系统默认模型。
与 job 执行器(``app/gateway/deep_research_job_executor.py``)的差异:
- 不建会话 / 任务 / 事件库行——生命周期就是本次聊天 run;
- 产物写入器定向到聊天线程(执行器定向到会话的隐藏 ``dr_`` 线程);
- 事件不落库,经 LangGraph 的 ``get_stream_writer()`` custom 通道直达前端
``onCustomEvent``(与子智能体 ``task_running`` 事件同一通道),帧统一带
``{"type": "deep_research_report", ...}`` 前缀。
"""
from __future__ import annotations
import logging
import re
from typing import Annotated, Any
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
from langchain_core.messages import HumanMessage, ToolMessage
from langgraph.types import Command
from langgraph.typing import ContextT
from deerflow.agents.deep_research.adapters.artifacts import ThreadOutputsArtifactWriter
from deerflow.agents.deep_research.adapters.context import DeerFlowContextCompressor
from deerflow.agents.deep_research.adapters.image import build_image_provider
from deerflow.agents.deep_research.adapters.llm import DeerFlowCompletionBackend
from deerflow.agents.deep_research.collection.thread_harvester import (
StaticHarvestMaterialProvider,
harvest_messages_materials,
)
from deerflow.agents.deep_research.config import DeepResearchConfig
from deerflow.agents.deep_research.engine import DeepResearchEngine
from deerflow.agents.deep_research.events import DeepResearchEvent, EventType, ResearchPhase
from deerflow.agents.deep_research.types import AdapterBundle, DeepResearchRequest, ResearchMaterial
from deerflow.agents.thread_state import ThreadState
from deerflow.persistence.report_structures.defaults import GENERAL_OUTLINE
from deerflow.runtime.thread_paths import resolve_path_user_id
logger = logging.getLogger(__name__)
# 收割池低于该条数视为「资料偏少」,仅记日志,不再打断用户。
_MIN_HARVESTED_MATERIALS = 3
# 引擎事件中值得转发到聊天的子集(model_usage / heartbeat / job_* 只对持久
# 任务管道有意义,聊天内是噪音)。
_FORWARDABLE_EVENTS: frozenset[str] = frozenset(
{
"phase_changed",
"plan_created",
"queries_planned",
"query_started",
"query_completed",
"source_added",
"sources_curated",
"context_compressed",
"report_reset",
"report_chunk",
"report_completed",
"summary_completed",
"artifact_created",
"warning",
"error",
}
)
# live-only 帧类型(不落库的 token 级增量,ReportChunkEmitter.publish_live)。
_FORWARDABLE_LIVE_EVENTS: frozenset[str] = frozenset({"report_delta", "report_thinking"})
REPORT_VIRTUAL_PATH = "/mnt/user-data/outputs/report.md"
def is_writing_mode_report_path(path: str | None) -> bool:
"""Only ``report.md`` counts as the writing-mode deliverable for follow-up edits.
Leftover notes / skill Markdown must not skip the first-report pipeline.
"""
if not path or not isinstance(path, str):
return False
normalized = path.replace("\\", "/").split("?", 1)[0].split("#", 1)[0].rstrip("/")
return normalized.lower().endswith("/report.md") or normalized.lower() == "report.md"
class StreamWriterEventSink:
"""把引擎事件经 LangGraph custom 通道转发到聊天前端。
满足 :class:`~deerflow.agents.deep_research.events.EventSink` 协议(结构
类型)。不持久化——``seq`` 恒为 0,聊天内没有 ``?after`` 重放需求;转发
失败只记日志,绝不影响研究执行。
"""
def __init__(
self,
writer: Any,
*,
session_id: str,
job_id: str,
) -> None:
self._writer = writer
self._session_id = session_id
self._job_id = job_id
async def emit(
self,
type: EventType, # noqa: A002 — 与协议参数名保持一致
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> DeepResearchEvent:
event = DeepResearchEvent(
seq=0,
session_id=self._session_id,
job_id=self._job_id,
type=type,
phase=phase,
payload=payload or {},
)
if type in _FORWARDABLE_EVENTS:
self._forward(event.to_sse_dict())
return event
async def publish_live(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> None:
if type not in _FORWARDABLE_LIVE_EVENTS:
return
self._forward(
{
"seq": 0,
"sessionId": self._session_id,
"jobId": self._job_id,
"type": type,
"phase": phase,
"payload": payload or {},
"live": True,
}
)
def _forward(self, frame: dict[str, Any]) -> None:
if self._writer is None:
return
try:
self._writer({"type": "deep_research_report", "event": frame})
except Exception: # noqa: BLE001 - 进度转发绝不影响研究本体
logger.debug("deep_research_report: custom stream frame dropped", exc_info=True)
# 写作模式常在「不用搜索 / 对话资料很少」时开写。工作台默认的「材料不足就
# 写明资料不足」会把报告写成元分析;这里强制用领域知识补全正文。
_KNOWLEDGE_WRITE_INSTRUCTION = (
"对话材料很少或用户要求直接开写时:必须基于模型自身的领域知识写成完整、有实质内容的研究报告"
"(含架构说明;用户要求流程图时用 Mermaid)。禁止把「材料不足/未提供文献/现有材料高度浓缩」"
"写成报告主线或用其填充多个章节。参考文献可标为基于公开领域知识,不要用「材料未提供」占整节。"
)
def build_writing_research_config(
*,
focus: str | None = None,
thinking_enabled: bool = False,
model_name: str | None = None,
) -> DeepResearchConfig:
"""组装聊天写作模式的研究配置:basic + 通用分析结构 + adaptive。
与深度研究工作台确认卡的默认值一致(``ReportConfigCard.DEFAULT_ADVANCED_OPTIONS``)。
``model_name`` / ``thinking_enabled`` 继承自聊天 run 的模型选择——同一模型
覆盖 fast/smart/strategic 三个角色,使报告管线与对话用同一个模型和思考
开关(缺省回落系统默认模型)。
"""
parts: list[str] = []
if focus and focus.strip():
parts.append(focus.strip())
parts.append(_KNOWLEDGE_WRITE_INSTRUCTION)
return DeepResearchConfig(
mode="basic",
collection_mode="legacy",
custom_outline=GENERAL_OUTLINE,
structure_mode="adaptive",
generate_images=False,
thinking_enabled=thinking_enabled,
fast_model=model_name,
smart_model=model_name,
strategic_model=model_name,
report_instruction="\n".join(parts),
).clamp()
def _resolve_chat_model(context: dict[str, Any] | None) -> tuple[str | None, bool, bool]:
"""从 run 上下文解析聊天选择的模型与思考开关(P2:管线继承聊天模型)。
Returns ``(model_name, thinking_enabled, force_disable_thinking)``。模型名
对不上 config.yaml 时回落 ``None``(系统默认);模型不支持思考时关思考,
语义与 lead agent 的解析一致(``_make_lead_agent``)。
"""
cfg = context or {}
name = cfg.get("model_name") or cfg.get("model") or None
thinking = bool(cfg.get("thinking_enabled", True))
force_disable = bool(cfg.get("thinking_force_disabled", False))
name = str(name).strip() if isinstance(name, str) else None
if not name:
return None, thinking, force_disable
try:
from deerflow.config.app_config import get_app_config
model_config = get_app_config().get_model_config(name)
except Exception: # noqa: BLE001 - 配置不可用时交由 create_chat_model 自行兜底
logger.warning("[deep_research_report] app config unavailable; passing model through: %s", name)
return name, thinking, force_disable
if model_config is None:
logger.warning("[deep_research_report] chat model '%s' not in app config; using system default", name)
return None, thinking, force_disable
if thinking and not model_config.supports_thinking:
thinking = False
return name, thinking, force_disable
# ── 当前主题相关度强过滤(P1:旧课题资料不得凑门槛、不得入报告) ────────────
# 主题切词:ASCII 词(≥2 字符)+ CJK 连续段的全部 bigram;≥4 字的整段额外
# 作为强词(命中标题即认定相关)。
_ASCII_WORD_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]+")
_CJK_RUN_RE = re.compile(r"[\u4e00-\u9fff]+")
_STRONG_TERM_MIN_CHARS = 4
# 词面命中判定:标题 ≥2 个不同词,或正文 ≥4 个不同词,或 标题≥1 且正文≥2,
# 或强词(整段主题短语)出现在标题。
_TITLE_MIN_HITS = 2
_CONTENT_MIN_HITS = 4
# 正文只扫前若干字符——相关度信号在开头最密,长文省 CPU。
_CONTENT_SCAN_CHARS = 4000
def _topic_terms(topic: str) -> tuple[frozenset[str], frozenset[str]]:
"""切出 ``(强词, 弱词)``:强词=主题整段短语,弱词=bigram + ASCII 词。"""
weak: set[str] = set()
strong: set[str] = set()
for word in _ASCII_WORD_RE.findall(topic):
weak.add(word.lower())
for run in _CJK_RUN_RE.findall(topic):
if len(run) >= _STRONG_TERM_MIN_CHARS:
strong.add(run)
for i in range(len(run) - 1):
weak.add(run[i : i + 2])
return frozenset(strong), frozenset(weak)
def _is_topic_relevant(material: ResearchMaterial, strong: frozenset[str], weak: frozenset[str]) -> bool:
title = (material.title or "").lower()
content = (material.raw_content or "")[:_CONTENT_SCAN_CHARS].lower()
title_hits = sum(1 for term in weak if term in title)
content_hits = sum(1 for term in weak if term in content)
if any(term in title for term in strong):
return True
if title_hits >= _TITLE_MIN_HITS:
return True
if content_hits >= _CONTENT_MIN_HITS:
return True
if title_hits >= 1 and content_hits >= 2:
return True
# 短主题兜底:切出的词 ≤2 个时(如「课题」「AI」),命中任意一词即相关。
return len(weak) <= 2 and (title_hits + content_hits) >= 1
def _filter_relevant_materials(
materials: list[ResearchMaterial],
*,
topic: str,
anchor_index: int | None = None,
) -> tuple[list[ResearchMaterial], int]:
"""按当前主题过滤收割池;返回 ``(相关池, 被剔除条数)``。
两条保留通道(满足其一即入池):
1. **位置**:材料来自课题请求消息(``anchor_index``)之后的工具消息——
那是模型为本课题检索的,与词面/语言无关,一律保留。线上实测中文课题
+ 英文检索结果会被纯词面匹配整批误杀(35 条只留 4 条)。
2. **词面**:材料词面命中课题(强词/标题/正文规则)——兜住课题切换前
的旧检索里仍与当前课题相关的部分。
``anchor_index`` 之前的旧课题检索(词面不命中)继续被剔除(P1:旧课题
资料不得凑门槛、不得入报告)。``anchor_index=None`` 或负数(对话里找不
到课题请求消息,如纯工具消息的旧调用方)退化为纯词面过滤。
"""
strong, weak = _topic_terms(topic)
if not strong and not weak:
return list(materials), 0
positional = anchor_index is not None and anchor_index >= 0
relevant: list[ResearchMaterial] = []
for material in materials:
message_index = material.metadata.get("message_index")
if positional and isinstance(message_index, int) and message_index > anchor_index:
relevant.append(material)
continue
if _is_topic_relevant(material, strong, weak):
relevant.append(material)
return relevant, len(materials) - len(relevant)
def _anchor_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
return not kwargs.get("hide_from_ui")
def _anchor_is_clarification_result(message: Any) -> bool:
return isinstance(message, ToolMessage) and str(getattr(message, "name", "") or "") == "ask_clarification"
def _anchor_message_text(message: Any) -> str:
content = getattr(message, "content", "")
if isinstance(content, list):
parts: list[str] = []
for part in content:
if isinstance(part, str):
parts.append(part)
elif isinstance(part, dict) and isinstance(part.get("text"), str):
parts.append(part["text"])
return " ".join(parts).strip()
return str(content or "").strip()
def topic_anchor_index(messages: list[Any], *, topic: str = "") -> int:
"""课题请求消息在对话中的位置(写作模式首报轮的资料过滤锚点)。
规则与 ``writing_mode_report_middleware.extract_report_topic`` 一致:取
最新的可见人类消息、跳过对 ``ask_clarification`` 的直接回答(紧跟澄清
ToolMessage 的人类消息不是新课题)。传入 ``topic`` 时优先返回与其文本
前缀一致的消息位置(模型原样复述课题的常见情形)。找不到返回 -1。
"""
normalized_topic = " ".join(str(topic or "").split())
prefix = normalized_topic[:80]
fallback = -1
for index in range(len(messages) - 1, -1, -1):
message = messages[index]
if not _anchor_visible_human(message):
continue
if index > 0 and _anchor_is_clarification_result(messages[index - 1]):
continue
text = " ".join(_anchor_message_text(message).split())
if not text:
continue
if prefix and text.startswith(prefix):
return index
if fallback < 0:
fallback = index
return fallback
def _safe_stream_writer() -> Any:
"""获取当前 run 的 custom 事件写入器;非流式上下文返回 None。"""
try:
from langgraph.config import get_stream_writer
return get_stream_writer()
except Exception: # noqa: BLE001 - 非流式运行(测试/后台)没有 writer
return None
@tool("deep_research_report", parse_docstring=True)
async def deep_research_report_tool(
runtime: ToolRuntime[ContextT, ThreadState],
tool_call_id: Annotated[str, InjectedToolCallId],
topic: str,
focus: str | None = None,
retrieve: bool | None = None,
) -> Command:
"""Run the deep-research report pipeline on the conversation's materials and produce report.md as the writing-mode deliverable.
Call this AT DELIVERY TIME — when the conversation has gathered enough substance
and the user expects the report file now (they asked to start writing, or you have
finished discussing and the report is the natural next step). Before that, work
exactly as usual (chat, search, clarify); do NOT call this tool early.
The tool harvests the materials already produced in this conversation (search /
knowledge / skill / file tool results) and writes a full research report
(general-analysis structure, numbered reference section) to
/mnt/user-data/outputs/report.md in this thread. The file is presented
automatically; do NOT write the report body yourself with write_file.
If the harvested pool is thin (or little of it matches the current topic), the
tool still starts the writing pipeline immediately with whatever relevant
materials exist — do NOT ask the user whether to search for more, and do NOT
call ask_clarification for that reason. Search in the conversation first with
your normal tools; this tool only writes the file.
Args:
topic: The research topic / thesis to investigate. Copy the user's subject faithfully;
do not paraphrase it into something narrower unless the user asked for that scope.
focus: Optional extra write-time requirements from the user (length, tone, must-cover
points, language preferences). Omit when the user gave none.
retrieve: Ignored. Kept for older callers; the writing-mode pipeline never
searches. False / omitted / True all write from conversation materials only.
tool_call_id: Injected tool call id.
"""
# 与 present_file_tool 相同的解析顺序:runtime.context → runtime.config。
thread_id = runtime.context.get("thread_id") if runtime.context else None
if not thread_id:
thread_id = ((getattr(runtime, "config", None) or {}).get("configurable") or {}).get("thread_id")
thread_id = str(thread_id) if thread_id else ""
if not thread_id:
return Command(
update={
"messages": [
ToolMessage(
content="Error: deep_research_report could not resolve the current thread id.",
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
query = topic.strip()
state = getattr(runtime, "state", None) or {}
conversation_messages = state.get("messages") or []
harvested, _agent_summary = harvest_messages_materials(conversation_messages, query=query)
# 课题请求之后的检索结果整批保留(那是模型为本课题检索的);只有课题
# 切换前的旧检索才按词面强过滤(旧课题资料不得凑门槛、不得入报告)。
anchor_index = topic_anchor_index(conversation_messages, topic=query)
materials, dropped_count = _filter_relevant_materials(harvested, topic=query, anchor_index=anchor_index)
harvested_count = len(materials)
logger.info(
"[deep_research_report] thread=%s harvested %d materials from conversation (topic-relevant %d, off-topic dropped %d, anchor_index=%d)",
thread_id,
len(harvested),
harvested_count,
dropped_count,
anchor_index,
)
if harvested_count < _MIN_HARVESTED_MATERIALS:
logger.info(
"[deep_research_report] thread=%s thin materials (%d < %d); writing immediately",
thread_id,
harvested_count,
_MIN_HARVESTED_MATERIALS,
)
if retrieve is True:
logger.info(
"[deep_research_report] thread=%s ignoring retrieve=true; writing-mode pipeline writes from conversation materials only",
thread_id,
)
materials_provider: Any = StaticHarvestMaterialProvider(materials)
material_source = "对话资料"
user_id = resolve_path_user_id(str(thread_id))
session_id = f"chat-{thread_id}"
writer = _safe_stream_writer()
events = StreamWriterEventSink(writer, session_id=session_id, job_id=tool_call_id)
# P2:报告管线继承聊天选择的模型与思考开关,缺省回落系统默认模型。
model_name, thinking_enabled, force_disable_thinking = _resolve_chat_model(runtime.context)
research_config = build_writing_research_config(
focus=focus,
thinking_enabled=thinking_enabled,
model_name=model_name,
)
llm_backend = DeerFlowCompletionBackend(
research_config,
event_sink=events,
force_disable_thinking=force_disable_thinking,
)
bundle = AdapterBundle(
llm=llm_backend,
materials=materials_provider,
context=DeerFlowContextCompressor(llm=llm_backend),
artifacts=ThreadOutputsArtifactWriter(str(thread_id), user_id=user_id or None),
events=events,
images=build_image_provider(),
)
request = DeepResearchRequest(
session_id=session_id,
user_id=user_id,
query=query,
config=research_config,
request_id=tool_call_id,
)
logger.info(
"[deep_research_report] thread=%s starting inline research (topic=%.80r, source=%s, harvested=%d)",
thread_id,
topic,
material_source,
harvested_count,
)
result = None
error_message: str | None = None
try:
result = await DeepResearchEngine().run(request, adapters=bundle)
except Exception as exc: # noqa: BLE001 - 工具错误以 ToolMessage 回给模型自纠
logger.exception("[deep_research_report] thread=%s research failed", thread_id)
error_message = f"深度研究报告生成失败:{exc}"
# 终态帧:无论成败都发,前端据此收尾进度条 / 停止流式预览。
if writer is not None:
try:
writer(
{
"type": "deep_research_report",
"event": {
"type": "tool_finished",
"sessionId": session_id,
"jobId": tool_call_id,
"phase": "done" if result is not None else "error",
"payload": {
"status": "success" if result is not None else "error",
**({"error": error_message} if error_message else {}),
},
},
}
)
except Exception: # noqa: BLE001
logger.debug("[deep_research_report] tool_finished frame dropped", exc_info=True)
if result is None:
return Command(
update={
"messages": [
ToolMessage(
content=f"Error: {error_message}. 收集资料或模型调用可能暂时不可用,可建议用户稍后重试。",
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
source_count = len(result.source_ids or [])
summary = f"研究报告已完成:基于 {source_count} 条资料({material_source})按「通用分析结构」撰写,已写入 {REPORT_VIRTUAL_PATH} 并展示给用户。请用 2-3 句话向用户简要总结报告的核心结论,不要复述全文。"
logger.info(
"[deep_research_report] thread=%s completed (sources=%d, report_chars=%d)",
thread_id,
source_count,
len(result.report_markdown or ""),
)
return Command(
update={
"artifacts": [REPORT_VIRTUAL_PATH],
"messages": [ToolMessage(content=summary, tool_call_id=tool_call_id, name="deep_research_report")],
},
)
__all__ = [
"REPORT_VIRTUAL_PATH",
"StreamWriterEventSink",
"build_writing_research_config",
"deep_research_report_tool",
"is_writing_mode_report_path",
"topic_anchor_index",
]
@@ -0,0 +1,155 @@
"""Memory V2 - Hindsight 的 3 个 LangChain 工具。
仅当 ``config.memory.hindsight.memory_mode`` 为 ``tools`` 或 ``hybrid`` 时,
这些工具才会被 ``get_available_tools`` 加入工具集 (``context`` 模式不暴露)。
- hindsight_recall 多策略检索 (语义 + 实体图谱),查双 bank
- hindsight_reflect 跨记忆综合 (LLM 推理)
- hindsight_retain 主动存储一条记忆到全局 user bank
与 builtin 的 ``memory`` 工具一样,这些工具从 :class:`ToolRuntime` 与请求上下文
解析 user_id / agent_id,按生效配置懒建一个 :class:`HindsightProvider` 后调用。
"""
from __future__ import annotations
import json
import logging
from langchain.tools import ToolRuntime, tool
from langgraph.config import get_config
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config.memory_config import get_effective_memory_config
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
"""从 runtime context / RunnableConfig 解析 agent_id,缺省 ``"default"``。"""
agent_id = runtime.context.get("agent_id") if runtime.context else None
if agent_id:
return str(agent_id)
runtime_config = getattr(runtime, "config", None) or {}
agent_id = runtime_config.get("configurable", {}).get("agent_id")
if agent_id:
return str(agent_id)
try:
agent_id = get_config().get("configurable", {}).get("agent_id")
except RuntimeError:
agent_id = None
return str(agent_id) if agent_id else "default"
def _build_provider(runtime: ToolRuntime[ContextT, ThreadState]):
"""按生效配置懒建并初始化一个 HindsightProvider;不可用时返回 ``None``。"""
from deerflow.agents.memory.providers.hindsight import HindsightProvider
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
if not config.enabled or config.provider != "hindsight":
return None
provider = HindsightProvider(config.hindsight)
if not provider.is_available():
return None
thread_id = runtime.context.get("thread_id") if runtime.context else None
provider.initialize(
user_id=user_id,
agent_id=_resolve_agent_id(runtime),
thread_id=thread_id or "",
base_dir="",
)
return provider
@tool("hindsight_recall", parse_docstring=True)
def hindsight_recall_tool(
runtime: ToolRuntime[ContextT, ThreadState],
query: str,
) -> str:
"""检索 Hindsight 长期记忆,查找与 query 相关的历史信息。
用于回答关于用户、过往会话、之前讨论过的内容的问题。会同时检索全局用户
记忆和当前 agent 的工作记忆。
Args:
query: 检索查询,描述你想找回什么信息。
"""
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
results = provider.recall(query)
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_recall 失败:%s", exc)
return json.dumps({"success": False, "error": f"检索失败:{exc}"}, ensure_ascii=False)
if not results:
return json.dumps({"success": True, "result": "没有找到相关记忆。"}, ensure_ascii=False)
lines = "\n".join(f"{i}. {text}" for i, text in enumerate(results, 1))
return json.dumps({"success": True, "result": lines}, ensure_ascii=False)
@tool("hindsight_reflect", parse_docstring=True)
def hindsight_reflect_tool(
runtime: ToolRuntime[ContextT, ThreadState],
query: str,
) -> str:
"""对 Hindsight 记忆做跨记忆综合推理,得到一段综合性回答。
与 hindsight_recall 返回原始记忆片段不同,reflect 会让 LLM 综合多条记忆
给出推理结论。适合需要归纳、总结、跨记忆关联的问题。
Args:
query: 你希望综合分析的问题。
"""
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
text = provider.reflect(query)
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_reflect 失败:%s", exc)
return json.dumps({"success": False, "error": f"综合失败:{exc}"}, ensure_ascii=False)
return json.dumps(
{"success": True, "result": text or "没有找到相关记忆。"}, ensure_ascii=False
)
@tool("hindsight_retain", parse_docstring=True)
def hindsight_retain_tool(
runtime: ToolRuntime[ContextT, ThreadState],
content: str,
) -> str:
"""主动把一条信息存入 Hindsight 的全局用户记忆库。
用于记录跨会话、跨 agent 仍有价值的用户事实。Hindsight 会自动做实体抽取
和知识图谱关联。
Args:
content: 要存储的记忆内容。
"""
if not content or not content.strip():
return json.dumps({"success": False, "error": "content 不能为空。"}, ensure_ascii=False)
provider = _build_provider(runtime)
if provider is None:
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
try:
provider.retain_to_user_bank(content.strip())
except Exception as exc: # noqa: BLE001
logger.warning("hindsight_retain 失败:%s", exc)
return json.dumps({"success": False, "error": f"存储失败:{exc}"}, ensure_ascii=False)
return json.dumps({"success": True, "result": "记忆已存储。"}, ensure_ascii=False)
#: 三个 Hindsight 工具,供 get_available_tools 在 tools/hybrid 模式下加入。
HINDSIGHT_TOOLS = [hindsight_recall_tool, hindsight_reflect_tool, hindsight_retain_tool]
__all__ = [
"hindsight_recall_tool",
"hindsight_reflect_tool",
"hindsight_retain_tool",
"HINDSIGHT_TOOLS",
]
@@ -0,0 +1,257 @@
"""Built-in tool for invoking external ACP-compatible agents."""
import logging
import os
import shutil
from typing import Annotated, Any
from langchain_core.runnables import RunnableConfig
from langchain_core.tools import BaseTool, InjectedToolArg, StructuredTool
from pydantic import BaseModel, Field
logger = logging.getLogger(__name__)
class _InvokeACPAgentInput(BaseModel):
agent: str = Field(description="Name of the ACP agent to invoke")
prompt: str = Field(description="The concise task prompt to send to the agent")
def _get_work_dir(thread_id: str | None) -> str:
"""Get the per-thread ACP workspace directory.
Each thread gets an isolated workspace under
``{base_dir}/threads/{thread_id}/acp-workspace/`` so that concurrent
sessions cannot read or overwrite each other's ACP agent outputs.
Falls back to the legacy global ``{base_dir}/acp-workspace/`` when
``thread_id`` is not available (e.g. embedded / direct invocation).
The directory is created automatically if it does not exist.
Returns:
An absolute physical filesystem path to use as the working directory.
"""
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
paths = get_paths()
if thread_id:
try:
work_dir = paths.acp_workspace_dir(thread_id, user_id=get_effective_user_id())
except ValueError:
logger.warning("Invalid thread_id %r for ACP workspace, falling back to global", thread_id)
work_dir = paths.base_dir / "acp-workspace"
else:
work_dir = paths.base_dir / "acp-workspace"
work_dir.mkdir(parents=True, exist_ok=True)
logger.info("ACP agent work_dir: %s", work_dir)
return str(work_dir)
def _build_mcp_servers() -> dict[str, dict[str, Any]]:
"""Build ACP ``mcpServers`` config from DeerFlow's enabled MCP servers."""
from deerflow.config.extensions_config import ExtensionsConfig
from deerflow.mcp.client import build_servers_config
return build_servers_config(ExtensionsConfig.from_file())
def _build_acp_mcp_servers() -> list[dict[str, Any]]:
"""Build ACP ``mcpServers`` payload for ``new_session``.
The ACP client expects a list of server objects, while DeerFlow's MCP helper
returns a name -> config mapping for the LangChain MCP adapter. This helper
converts the enabled servers into the ACP wire format.
"""
from deerflow.config.extensions_config import ExtensionsConfig
extensions_config = ExtensionsConfig.from_file()
enabled_servers = extensions_config.get_enabled_mcp_servers()
mcp_servers: list[dict[str, Any]] = []
for name, server_config in enabled_servers.items():
transport_type = server_config.type or "stdio"
payload: dict[str, Any] = {"name": name, "type": transport_type}
if transport_type == "stdio":
if not server_config.command:
raise ValueError(f"MCP server '{name}' with stdio transport requires 'command' field")
payload["command"] = server_config.command
payload["args"] = server_config.args
payload["env"] = [{"name": key, "value": value} for key, value in server_config.env.items()]
elif transport_type in ("http", "sse"):
if not server_config.url:
raise ValueError(f"MCP server '{name}' with {transport_type} transport requires 'url' field")
payload["url"] = server_config.url
payload["headers"] = [{"name": key, "value": value} for key, value in server_config.headers.items()]
else:
raise ValueError(f"MCP server '{name}' has unsupported transport type: {transport_type}")
mcp_servers.append(payload)
return mcp_servers
def _build_permission_response(options: list[Any], *, auto_approve: bool) -> Any:
"""Build an ACP permission response.
When ``auto_approve`` is True, selects the first ``allow_once`` (preferred)
or ``allow_always`` option. When False (the default), always cancels —
permission requests must be handled by the ACP agent's own policy or the
agent must be configured to operate without requesting permissions.
"""
from acp import RequestPermissionResponse
from acp.schema import AllowedOutcome, DeniedOutcome
if auto_approve:
for preferred_kind in ("allow_once", "allow_always"):
for option in options:
if getattr(option, "kind", None) != preferred_kind:
continue
option_id = getattr(option, "option_id", None)
if option_id is None:
option_id = getattr(option, "optionId", None)
if option_id is None:
continue
return RequestPermissionResponse(
outcome=AllowedOutcome(outcome="selected", optionId=option_id),
)
return RequestPermissionResponse(outcome=DeniedOutcome(outcome="cancelled"))
def _format_invocation_error(agent: str, cmd: str, exc: Exception) -> str:
"""Return a user-facing ACP invocation error with actionable remediation."""
if not isinstance(exc, FileNotFoundError):
return f"Error invoking ACP agent '{agent}': {exc}"
message = f"Error invoking ACP agent '{agent}': Command '{cmd}' was not found on PATH."
if cmd == "codex-acp" and shutil.which("codex"):
return f"{message} The installed `codex` CLI does not speak ACP directly. Install a Codex ACP adapter (for example `npx @zed-industries/codex-acp`) or update `acp_agents.codex.command` and `args` in config.yaml."
return f"{message} Install the agent binary or update `acp_agents.{agent}.command` in config.yaml."
def build_invoke_acp_agent_tool(agents: dict) -> BaseTool:
"""Create the ``invoke_acp_agent`` tool with a description generated from configured agents.
The tool description includes the list of available agents so that the LLM
knows which agents it can invoke without requiring hardcoded names.
Args:
agents: Mapping of agent name -> ``ACPAgentConfig``.
Returns:
A LangChain ``BaseTool`` ready to be included in the tool list.
"""
agent_lines = "\n".join(f"- {name}: {cfg.description}" for name, cfg in agents.items())
description = (
"Invoke an external ACP-compatible agent and return its final response.\n\n"
"Available agents:\n"
f"{agent_lines}\n\n"
"IMPORTANT: ACP agents operate in their own independent workspace. "
"Do NOT include /mnt/user-data paths in the prompt. "
"Give the agent a self-contained task description — it will produce results in its own workspace. "
"After the agent completes, its output files are accessible at /mnt/acp-workspace/ (read-only)."
)
# Capture agents in closure so the function can reference it
_agents = dict(agents)
async def _invoke(agent: str, prompt: str, config: Annotated[RunnableConfig, InjectedToolArg] = None) -> str:
logger.info("Invoking ACP agent %s (prompt length: %d)", agent, len(prompt))
logger.debug("Invoking ACP agent %s with prompt: %.200s%s", agent, prompt, "..." if len(prompt) > 200 else "")
if agent not in _agents:
available = ", ".join(_agents.keys())
return f"Error: Unknown agent '{agent}'. Available: {available}"
agent_config = _agents[agent]
thread_id: str | None = ((config or {}).get("configurable") or {}).get("thread_id")
try:
from acp import PROTOCOL_VERSION, Client, text_block
from acp.schema import ClientCapabilities, Implementation
except ImportError:
return "Error: agent-client-protocol package is not installed. Run `uv sync` to install project dependencies."
class _CollectingClient(Client):
"""Minimal ACP Client that collects streamed text from session updates."""
def __init__(self) -> None:
self._chunks: list[str] = []
@property
def collected_text(self) -> str:
return "".join(self._chunks)
async def session_update(self, session_id: str, update, **kwargs) -> None: # type: ignore[override]
try:
from acp.schema import TextContentBlock
if hasattr(update, "content") and isinstance(update.content, TextContentBlock):
self._chunks.append(update.content.text)
except Exception:
pass
async def request_permission(self, options, session_id: str, tool_call, **kwargs): # type: ignore[override]
response = _build_permission_response(options, auto_approve=agent_config.auto_approve_permissions)
outcome = response.outcome.outcome
if outcome == "selected":
logger.info("ACP permission auto-approved for tool call %s in session %s", tool_call.tool_call_id, session_id)
else:
logger.warning("ACP permission denied for tool call %s in session %s (set auto_approve_permissions: true in config.yaml to enable)", tool_call.tool_call_id, session_id)
return response
client = _CollectingClient()
cmd = agent_config.command
args = agent_config.args or []
physical_cwd = _get_work_dir(thread_id)
try:
mcp_servers = _build_acp_mcp_servers()
except ValueError as exc:
logger.warning(
"Invalid MCP server configuration for ACP agent '%s'; continuing without MCP servers: %s",
agent,
exc,
)
mcp_servers = []
agent_env: dict[str, str] | None = None
if agent_config.env:
agent_env = {k: (os.environ.get(v[1:], "") if v.startswith("$") else v) for k, v in agent_config.env.items()}
try:
from acp import spawn_agent_process
async with spawn_agent_process(client, cmd, *args, env=agent_env, cwd=physical_cwd) as (conn, proc):
logger.info("Spawning ACP agent '%s' with command '%s' and args %s in cwd %s", agent, cmd, args, physical_cwd)
await conn.initialize(
protocol_version=PROTOCOL_VERSION,
client_capabilities=ClientCapabilities(),
client_info=Implementation(name="deerflow", title="DeerFlow", version="0.1.0"),
)
session_kwargs: dict[str, Any] = {"cwd": physical_cwd, "mcp_servers": mcp_servers}
if agent_config.model:
session_kwargs["model"] = agent_config.model
session = await conn.new_session(**session_kwargs)
await conn.prompt(
session_id=session.session_id,
prompt=[text_block(prompt)],
)
result = client.collected_text
logger.info("ACP agent '%s' returned %s", agent, result[:1000])
logger.info("ACP agent '%s' returned %d characters", agent, len(result))
return result or "(no response)"
except Exception as e:
logger.error("ACP agent '%s' invocation failed: %s", agent, e)
return _format_invocation_error(agent, cmd, e)
return StructuredTool.from_function(
name="invoke_acp_agent",
description=description,
coroutine=_invoke,
args_schema=_InvokeACPAgentInput,
)
@@ -0,0 +1,134 @@
"""Authorized read-only WeKnora retrieval for cmzs Q&A."""
from __future__ import annotations
import json
import re
from collections.abc import Mapping
from typing import Any
from langchain.tools import ToolRuntime, tool
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config import get_app_config
from deerflow.config.agents_config import load_agent_config
from deerflow.integrations.weknora.local_index.runtime import get_local_wiki_retrieval_service
from deerflow.integrations.weknora.local_index.search import WikiIndexError
from deerflow.integrations.weknora.runtime import get_llmwiki_store, get_resolved_llmwiki_runtime
from deerflow.runtime.user_context import get_current_user, get_effective_user_id
_CONVERSATION_DEPOSIT_NAME = "对话沉淀"
_CONVERSATION_DEPOSIT_OWNER_USER_ID = "system"
_LEGACY_BRAND_PATTERN = re.compile(r"deer[\s_-]*flow", re.IGNORECASE)
def _is_conversation_deposit_mapping(row: Mapping[str, Any]) -> bool:
return str(row.get("owner_user_id") or "") == _CONVERSATION_DEPOSIT_OWNER_USER_ID and str(row.get("name") or "").strip() == _CONVERSATION_DEPOSIT_NAME
def _sanitize_conversation_deposit_value(value: Any) -> Any:
if isinstance(value, str):
return _LEGACY_BRAND_PATTERN.sub("cmzs", value)
if isinstance(value, dict):
return {key: _sanitize_conversation_deposit_value(item) for key, item in value.items()}
if isinstance(value, list):
return [_sanitize_conversation_deposit_value(item) for item in value]
if isinstance(value, tuple):
return tuple(_sanitize_conversation_deposit_value(item) for item in value)
return value
def selected_knowledge_base_ids(context: Mapping[str, Any] | None) -> list[str] | None:
"""Read the conversation selection; ``None`` means legacy/no selection key."""
if not context or "llmwiki_knowledge_base_ids" not in context:
return None
raw = context.get("llmwiki_knowledge_base_ids")
if not isinstance(raw, list):
return []
return list(dict.fromkeys(str(item).strip() for item in raw if str(item).strip()))[:100]
def _agent_allowed_ids(context: Mapping[str, Any] | None) -> list[str] | None:
agent_id = str((context or {}).get("agent_id") or "").strip()
if not agent_id or agent_id in {"default", "lead_agent"}:
return None
try:
config = load_agent_config(agent_id)
except (FileNotFoundError, ValueError):
return []
return list(config.llmwiki_knowledge_base_ids or []) if config else []
@tool("llmwiki_search", parse_docstring=True)
async def llmwiki_search_tool(
query: str,
runtime: ToolRuntime[ContextT, ThreadState],
) -> str:
"""Search the LLMWiki knowledge selected for this conversation.
Use this tool only when the current conversation explicitly selected one
or more LLMWiki knowledge bases. It only retrieves passages; it cannot
upload, edit, delete, publish or change permissions.
Args:
query: Focused natural-language retrieval query.
"""
local_config = get_app_config().llmwiki.local_wiki_index
resolved = get_resolved_llmwiki_runtime()
if not (local_config.enabled and local_config.internal_search_enabled) and not resolved.weknora_enabled:
return "LLMWiki retrieval is unavailable because no retrieval provider is enabled."
store = get_llmwiki_store()
user_id = get_effective_user_id()
is_admin = getattr(get_current_user(), "system_role", None) == "admin"
context = runtime.context if runtime.context else {}
selected_ids = selected_knowledge_base_ids(context)
allowed_ids = _agent_allowed_ids(context)
if selected_ids is None:
return "No LLMWiki knowledge base is selected for this conversation."
elif allowed_ids is not None and not set(selected_ids).issubset(set(allowed_ids)):
return "The conversation requested knowledge outside this agent's configured LLMWiki scope."
if selected_ids == []:
return "No LLMWiki knowledge base is selected for this conversation."
rows = []
for mapping_id in selected_ids:
row = await store.get_authorized(
mapping_id,
user_id,
write=False,
is_admin=is_admin,
)
if row is None:
return f"Knowledge base {mapping_id!r} is not available to the current user."
rows.append(row)
if not rows:
return "No authorized LLMWiki knowledge bases are available."
try:
payload = await get_local_wiki_retrieval_service().search(query.strip(), rows)
except (RuntimeError, WikiIndexError) as exc:
code = exc.code if isinstance(exc, WikiIndexError) else "WIKI_RETRIEVAL_UNAVAILABLE"
return f"LLMWiki Wiki-only retrieval failed ({code}); retrieval is unavailable, not empty."
mapping_by_id = {str(row["id"]): row for row in rows}
results = []
for item in payload["results"]:
mapping = mapping_by_id.get(str(item.get("knowledge_base_id") or ""))
visible = _sanitize_conversation_deposit_value(item) if mapping and _is_conversation_deposit_mapping(mapping) else item
results.append(visible)
return json.dumps(
{
"query": query,
"selection": [row["id"] for row in rows],
"knowledge_base_count": len(rows),
"mode": payload.get("mode") or "wiki_api",
"results": results,
"partial": payload.get("partial", False),
"warnings": payload.get("warnings", []),
"fallback_knowledge_base_ids": payload.get("fallback_knowledge_base_ids", []),
},
ensure_ascii=False,
)
@@ -0,0 +1,171 @@
"""Memory V2 - LLM 主动调用的 ``memory`` 工具。
让 LLM 在对话过程中主动把跨会话仍有用的信息记到持久化记忆里 ——
对应 Hermes 的 ``memory`` 工具,是双轨写入里的 "主动" 一轨。
工具写入直达 :class:`BuiltinFileProvider`:
- ``target="user"`` -> ``USER.md`` (用户画像,跨 agent 共享)
- ``target="memory"`` -> ``MEMORY.md`` (agent 私有工作笔记)
agent_id / user_id 在工具调用时从 :class:`ToolRuntime` 与请求上下文解析。
P2 期会在写入后追加 Hindsight 镜像 (``on_memory_write`` 钩子)。
"""
from __future__ import annotations
import json
import logging
from typing import Literal
from langchain.tools import ToolRuntime, tool
from langgraph.config import get_config
from langgraph.typing import ContextT
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
from deerflow.agents.thread_state import ThreadState
from deerflow.config.memory_config import get_effective_memory_config
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
"""从 runtime context / RunnableConfig 解析当前 agent_id,缺省为 ``"default"``。"""
agent_id = runtime.context.get("agent_id") if runtime.context else None
if agent_id:
return str(agent_id)
runtime_config = getattr(runtime, "config", None) or {}
agent_id = runtime_config.get("configurable", {}).get("agent_id")
if agent_id:
return str(agent_id)
try:
agent_id = get_config().get("configurable", {}).get("agent_id")
except RuntimeError:
agent_id = None
return str(agent_id) if agent_id else "default"
@tool("memory", parse_docstring=True)
def memory_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: Literal["add", "replace", "remove"],
target: Literal["memory", "user"],
content: str | None = None,
old_text: str | None = None,
) -> str:
"""把跨会话仍有用的信息记到持久化记忆里。
记忆会被注入到后续对话的系统提示词中,所以请保持简洁、只记真正还会用到的事实。
什么时候应该记 (主动判断,不必等用户开口):
- 用户纠正你,或者说 "记住这件事" / "下次别这样"
- 用户透露偏好、习惯、个人信息 (姓名、角色、时区、代码风格)
- 你发现了环境/项目/工具相关、之后还会复用的稳定事实
两类 target —— 拿不准时优先选 memory:
- memory:当前 agent 的私有记忆 (agent 隔离)。**默认选这个。**
只要用户是在对当前这个 agent 说话 —— 例如 "你以后……"、"和我说话时……"、
针对本助手的语气/开场白/回复风格/处理方式,以及环境事实、约定、踩过的坑 —— 一律记到 memory,
这样只影响当前 agent。
- user:用户画像 (跨所有 agent 共享)。仅当信息是**跨所有 agent 都通用**的客观身份事实时才用 ——
姓名、角色、时区、惯用语言。除非用户明确说 "所有助手都……",否则不要把沟通风格/偏好记到 user。
不要记:一次性任务进度、可以重新查到的信息、临时 TODO 状态。
Args:
action: 操作类型。add 新增条目;replace 替换 (用 old_text 定位);remove 删除 (用 old_text 定位)。
target: 记忆类别。默认用 memory (当前 agent 私有);只有跨所有 agent 通用的用户身份事实才用 user。
content: 条目内容。action 为 add 或 replace 时必填。
old_text: 短唯一子串,用于定位要替换或删除的条目。action 为 replace 或 remove 时必填。
"""
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
if not config.enabled:
return json.dumps(
{"success": False, "error": "记忆功能未启用,可能在配置中被关闭。"},
ensure_ascii=False,
)
if getattr(config, "version", "v2") == "v1":
return json.dumps(
{"success": False, "error": "当前使用 V1 记忆模式,记忆由系统自动提取,不支持手动写入。"},
ensure_ascii=False,
)
if not config.builtin.enabled:
return json.dumps(
{"success": False, "error": "记忆功能未启用,可能在配置中被关闭。"},
ensure_ascii=False,
)
if target not in ("memory", "user"):
return json.dumps(
{"success": False, "error": f"非法 target '{target}',只能是 'memory' 或 'user'。"},
ensure_ascii=False,
)
agent_id = _resolve_agent_id(runtime)
provider = BuiltinFileProvider(
memory_char_limit=config.builtin.memory_char_limit,
user_char_limit=config.builtin.user_char_limit,
deduplicate_on_load=config.builtin.deduplicate_on_load,
security=config.security,
)
try:
provider.initialize(
user_id=user_id,
agent_id=agent_id,
base_dir=str(get_paths().base_dir),
)
except Exception as exc: # noqa: BLE001 - 初始化失败要返回给 LLM 而非崩溃
logger.warning("memory 工具初始化 BuiltinFileProvider 失败:%s", exc)
return json.dumps(
{"success": False, "error": f"记忆初始化失败:{exc}"}, ensure_ascii=False
)
if action == "add":
if not content:
result = {"success": False, "error": "action=add 需要提供 content。"}
else:
result = provider.add(target, content)
elif action == "replace":
if not old_text:
result = {"success": False, "error": "action=replace 需要提供 old_text。"}
elif not content:
result = {"success": False, "error": "action=replace 需要提供 content。"}
else:
result = provider.replace(target, old_text, content)
elif action == "remove":
if not old_text:
result = {"success": False, "error": "action=remove 需要提供 old_text。"}
else:
result = provider.remove(target, old_text)
else:
result = {"success": False, "error": f"未知 action '{action}',只能是 add / replace / remove。"}
# 写入成功后镜像到外部 provider (Hindsight)。失败不影响 builtin 写入结果。
if result.get("success") and action in ("add", "replace") and content:
_mirror_to_external(config, user_id, agent_id, thread_id="", action=action, target=target, content=content)
return json.dumps(result, ensure_ascii=False)
def _mirror_to_external(config, user_id: str, agent_id: str, *, thread_id: str, action: str, target: str, content: str) -> None:
"""把一次 builtin 记忆写入镜像到外部 provider (P2: Hindsight)。"""
if config.provider != "hindsight":
return
try:
from deerflow.agents.memory.providers.hindsight import HindsightProvider
provider = HindsightProvider(config.hindsight)
if not provider.is_available():
return
provider.initialize(user_id=user_id, agent_id=agent_id, thread_id=thread_id, base_dir="")
provider.on_memory_write(action, target, content, metadata={"user_id": user_id, "agent_id": agent_id})
except Exception as exc: # noqa: BLE001 - 镜像失败不影响 builtin 写入
logger.debug("memory 工具镜像到 Hindsight 失败:%s", exc)
__all__ = ["memory_tool"]
@@ -0,0 +1,71 @@
"""空间 RAG 检索工具。
从 LangGraph configurable 中读取 notebook_search_space_id / notebook_source_ids /
notebook_token,调用外部检索接口返回相关文本块,供 LLM 在空间模式下引用回答。
API base URL 通过环境变量 DEER_FLOW_NOTEBOOK_API_BASE 配置。
"""
from __future__ import annotations
import logging
import os
import httpx
from langchain.tools import tool
from langgraph.config import get_config
logger = logging.getLogger(__name__)
_SEARCH_PATH = "/api/v1/source/mentioned-documents/search"
def _notebook_api_base() -> str:
return (os.getenv("DEER_FLOW_NOTEBOOK_API_BASE") or "").rstrip("/")
@tool("search_notebook_sources", parse_docstring=True)
def notebook_search_tool(query: str, top_k: int = 10) -> str:
"""Search the notebook's knowledge sources to find relevant content.
Call this tool for EVERY user question. After retrieving results, cite
sources inline using [[cite:<document_id>]] markers immediately after
each claim, e.g. "违约金为0.5%[[cite:101]]".
Args:
query: The user's question or a refined search query.
top_k: Number of top chunks to retrieve (default 10).
"""
base = _notebook_api_base()
if not base:
return "Notebook API base URL not configured (DEER_FLOW_NOTEBOOK_API_BASE)."
cfg = get_config().get("configurable", {})
search_space_id: int | None = cfg.get("notebook_search_space_id")
source_ids: list[int] = cfg.get("notebook_source_ids") or []
token: str = cfg.get("notebook_token") or ""
if not search_space_id:
return "No notebook search space configured."
logger.info("notebook_search_tool query=%r source_ids=%s search_space_id=%s", query, source_ids, search_space_id)
try:
resp = httpx.post(
f"{base}{_SEARCH_PATH}",
headers={"Authorization": f"Bearer {token}"},
json={
"query": query,
"source_ids": source_ids,
"search_space_id": search_space_id,
"top_k": top_k,
},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
content = data.get("content") if isinstance(data, dict) else None
return content if content else "No relevant content found."
except Exception as e:
logger.warning("notebook_search_tool failed: %s", e)
return f"Search failed: {e}"
@@ -0,0 +1,322 @@
"""Thread-safe page-report template preparation and static quality checks."""
from __future__ import annotations
import json
import re
from collections.abc import Iterable
from pathlib import Path
from langchain.tools import ToolRuntime, tool
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
from deerflow.page_reports.templates import (
choose_template,
get_template_profile,
list_template_profiles,
resolve_template_file,
)
from deerflow.runtime.thread_paths import resolve_path_user_id
_MAX_HTML_BYTES = 4 * 1024 * 1024
# Allow human-readable Chinese filenames while still rejecting path separators,
# Windows-reserved filename characters, and control characters.
_SAFE_OUTPUT_NAME = re.compile(r'^[^<>:"/\\|?*\x00-\x1f]+\.html$', re.IGNORECASE)
_FONT_SIZE_RE = re.compile(r"font-size\s*:\s*([0-9]+(?:\.[0-9]+)?)px", re.IGNORECASE)
_MIN_TEXT_FONT_SIZE = 16.0
def _thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
context = runtime.context or {}
thread_id = context.get("thread_id")
if not thread_id:
thread_id = (getattr(runtime, "config", {}) or {}).get("configurable", {}).get("thread_id")
if not thread_id:
raise ValueError("当前会话缺少 thread_id,无法准备页面模板。")
return str(thread_id)
def _virtual_path(path: Path, *, thread_id: str, user_id: str | None) -> str:
root = get_paths().sandbox_user_data_dir(thread_id, user_id=user_id).resolve()
relative = path.resolve().relative_to(root)
return f"{VIRTUAL_PATH_PREFIX}/{relative.as_posix()}"
def _thread_directories(runtime: ToolRuntime[ContextT, ThreadState]) -> tuple[str, str | None, Path, Path]:
thread_id = _thread_id(runtime)
user_id = resolve_path_user_id(thread_id)
paths = get_paths()
workspace = paths.sandbox_work_dir(thread_id, user_id=user_id)
outputs = paths.sandbox_outputs_dir(thread_id, user_id=user_id)
workspace.mkdir(parents=True, exist_ok=True)
outputs.mkdir(parents=True, exist_ok=True)
return thread_id, user_id, workspace, outputs
def _safe_output_filename(output_name: str) -> str:
raw = (output_name or "report-page.html").strip()
if not raw.lower().endswith(".html"):
raw += ".html"
if Path(raw).name != raw or not _SAFE_OUTPUT_NAME.fullmatch(raw):
raise ValueError("output_name 必须是单个安全的 .html 文件名,不能包含路径或 Windows 非法字符。")
return raw
def _apply_minimum_font_size(html: str) -> str:
"""Normalize editable template copies to the report designer's font floor.
The library includes some legacy dashboard skeletons with compact labels.
They are useful layout starting points, but the designer contract requires
that visible text is at least 16px. Normalize the *per-thread copy* here
so a weaker model does not have to remember a large CSS-only cleanup before
it can work on the actual report content. The immutable source template is
never changed, and ``validate`` remains the final guard if later edits add
a smaller declaration.
"""
def replace(match: re.Match[str]) -> str:
size = float(match.group(1))
if size >= _MIN_TEXT_FONT_SIZE:
return match.group(0)
return f"font-size: {_MIN_TEXT_FONT_SIZE:g}px"
return _FONT_SIZE_RE.sub(replace, html)
def _edit_contract(template_id: str) -> dict[str, object]:
profile = get_template_profile(template_id)
chart_driven = "reportData" in profile.data_entry
return {
"data_entry": profile.data_entry,
"edit_order": [
"先把用户材料整理为文字摘要、指标、表格行、图表数据和待办事项。",
"只编辑工作区的副本;禁止改动模板源文件。",
"若存在 reportData,先改该对象中的图表数组,再替换标题、段落、卡片和表格文案。",
"根据材料删掉无数据的卡片或整页;不要为了凑页数保留空白面板。",
"将最终 HTML 写入 outputs 后调用 validate;通过后用 present_files 交付。",
],
"must_keep": (
["reportData 的字段名和图表渲染函数", "页面切换及 prefers-reduced-motion 逻辑"]
if chart_driven
else ["已有布局类名", "移动端 / reduced-motion 样式"]
),
"illustrative_data_rule": "没有可核验数值但用户明确要求图表时,可画示意图;页面必须在图例或数据口径处标注“示意数据 / 待补充数据”,不得伪装为事实。",
}
def _prepare(
runtime: ToolRuntime[ContextT, ThreadState],
*,
theme: str,
content_density: str,
required_features: list[str],
preferred_page_count: int | None,
selection_key: str,
exclude_template_ids: list[str],
template_id: str | None,
output_name: str,
page_brief: str,
) -> str:
profile = (
get_template_profile(template_id)
if (template_id or "").strip()
else choose_template(
theme=theme,
content_density=content_density,
required_features=required_features,
preferred_page_count=preferred_page_count,
selection_key=selection_key,
exclude_template_ids=exclude_template_ids,
)
)
source = resolve_template_file(profile.id)
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
filename = _safe_output_filename(output_name)
working_copy = workspace / f"{Path(filename).stem}--{profile.id}.html"
brief_path = workspace / f"{Path(filename).stem}--page-brief.json"
# Copy first, then normalize only the editable thread-local copy. This
# preserves the bundled assets exactly as supplied while giving every run a
# usable 16px-or-larger starting point.
working_copy.write_text(_apply_minimum_font_size(source.read_text(encoding="utf-8")), encoding="utf-8")
brief = {
"template": profile.to_dict(),
"requested_theme": theme or "auto",
"requested_content_density": content_density or "balanced",
"required_features": required_features,
"recommended_final_output": _virtual_path(outputs / filename, thread_id=thread_id, user_id=user_id),
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
"user_material_brief": (page_brief or "").strip(),
"edit_contract": _edit_contract(profile.id),
"font_rule": "所有可见文字最小字号为 16px;生成后必须通过 validate 校验。",
}
brief_path.write_text(json.dumps(brief, ensure_ascii=False, indent=2), encoding="utf-8")
return json.dumps(
{
"ok": True,
"template": profile.to_dict(),
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
"brief_path": _virtual_path(brief_path, thread_id=thread_id, user_id=user_id),
"final_output": brief["recommended_final_output"],
"next_step": "读取 brief_path 和 working_copy,改完后写入 final_output,再调用 action=validate。",
},
ensure_ascii=False,
)
def _resolve_current_thread_file(
runtime: ToolRuntime[ContextT, ThreadState],
virtual_path: str,
) -> tuple[Path, str, str | None]:
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
normalized = (virtual_path or "").strip()
if not normalized.startswith(f"{VIRTUAL_PATH_PREFIX}/"):
raise ValueError(f"file_path 必须位于 {VIRTUAL_PATH_PREFIX}/workspace 或 {VIRTUAL_PATH_PREFIX}/outputs。")
actual = get_paths().resolve_virtual_path(thread_id, normalized, user_id=user_id)
permitted_roots: Iterable[Path] = (workspace.resolve(), outputs.resolve())
if not any(actual.is_relative_to(root) for root in permitted_roots):
raise ValueError("file_path 只能指向当前会话的 workspace 或 outputs 目录。")
if not actual.is_file():
raise ValueError(f"待校验 HTML 不存在:{virtual_path}")
return actual, thread_id, user_id
def _count_textual_content(html: str) -> int:
plain = re.sub(r"<script[\s\S]*?</script>|<style[\s\S]*?</style>|<[^>]+>", " ", html, flags=re.IGNORECASE)
return len(re.sub(r"\s+", "", plain))
def _quality_report(html: str, *, data_mode: str, expected_features: set[str]) -> dict[str, object]:
lowered = html.lower()
errors: list[str] = []
warnings: list[str] = []
if "<!doctype html" not in lowered or "</html>" not in lowered:
errors.append("HTML 不完整:需要 <!doctype html> 和 </html>。")
if "<body" not in lowered or "</body>" not in lowered:
errors.append("HTML 缺少完整 body 结构。")
if "<title" not in lowered:
errors.append("页面缺少 title。")
if _count_textual_content(html) < 500:
warnings.append("有效文字内容偏少;本类页面应以结论、要点、说明和行动项为主体。")
chart_markers = {"line": "svg", "bar": "bar", "pie": "pie", "radar": "radar", "scatter": "scatter", "gantt": "gantt"}
for feature in expected_features:
marker = chart_markers.get(feature)
if marker and marker not in lowered:
warnings.append(f"未检测到请求的 {feature} 图表结构,请确认是否应删去该要求或补充图表。")
font_sizes = [float(value) for value in _FONT_SIZE_RE.findall(html)]
too_small = sorted({value for value in font_sizes if value < 16})
if too_small:
errors.append("发现小于 16px 的字号:" + "、".join(f"{value:g}px" for value in too_small[:8]) + "。")
if (data_mode or "provided").strip().lower() in {"illustrative", "mixed"} and not any(
mark in html for mark in ("示意数据", "待补充数据", "模拟数据")
):
errors.append("示意图表没有标注“示意数据 / 待补充数据”,可能被误认为事实。")
if "reportdata" in lowered and "const reportdata" not in lowered:
warnings.append("检测到 reportData 引用但未检测到 const reportData 定义,请检查图表脚本。")
return {
"ok": not errors,
"errors": errors,
"warnings": warnings,
"metrics": {
"bytes": len(html.encode("utf-8")),
"text_characters": _count_textual_content(html),
"page_sections": len(re.findall(r"class=[\"'][^\"']*(?:report-page|page)[^\"']*[\"']", html, flags=re.IGNORECASE)),
"has_script": "<script" in lowered,
},
}
def _validate(
runtime: ToolRuntime[ContextT, ThreadState],
*,
file_path: str,
data_mode: str,
expected_features: list[str],
) -> str:
actual, thread_id, user_id = _resolve_current_thread_file(runtime, file_path)
if actual.stat().st_size > _MAX_HTML_BYTES:
raise ValueError(f"HTML 超过 {_MAX_HTML_BYTES // 1024 // 1024}MB,拒绝读取。")
html = actual.read_text(encoding="utf-8")
report = _quality_report(
html,
data_mode=data_mode,
expected_features={item.strip().lower() for item in expected_features if item.strip()},
)
report_path = actual.with_name(f"{actual.stem}.quality.json")
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
report["quality_report"] = _virtual_path(report_path, thread_id=thread_id, user_id=user_id)
report["file_path"] = _virtual_path(actual, thread_id=thread_id, user_id=user_id)
return json.dumps(report, ensure_ascii=False)
@tool("page_report_template", parse_docstring=True)
def page_report_template_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: str,
theme: str = "auto",
content_density: str = "balanced",
required_features: list[str] | None = None,
preferred_page_count: int | None = None,
selection_key: str = "",
exclude_template_ids: list[str] | None = None,
template_id: str | None = None,
output_name: str = "report-page.html",
page_brief: str = "",
file_path: str = "",
data_mode: str = "provided",
) -> str:
"""Select, copy, and quality-check reusable HTML report-page templates.
Use this tool instead of editing a source template in place.
Args:
action: One of ``catalog``, ``prepare``, or ``validate``. ``catalog`` lists
profiles; ``prepare`` selects/copies a source into this thread's
workspace and writes an editing brief; ``validate`` checks an edited
HTML file and writes a JSON quality report next to it.
theme: ``dark`` or ``light``. Use the UI-provided presentation theme when
available; ``auto`` lets the selector use all profiles.
content_density: ``text-heavy``, ``balanced``, or ``data-heavy``.
required_features: Needed components such as ``line``, ``pie``,
``radar``, ``scatter``, ``gantt``, ``table``, ``text-panels``.
preferred_page_count: Preferred number of report pages. The agent may
remove unused skeleton pages after preparation.
selection_key: Stable request/thread-derived text used to vary equally
good template choices.
exclude_template_ids: Recently-used template ids to avoid where possible.
template_id: Optional explicit catalog id. Omit to select automatically.
output_name: Final safe HTML filename, e.g. ``经营月报.html``.
page_brief: Concise summary of supplied materials and desired output.
file_path: For ``validate`` only: current-thread HTML under workspace or
outputs.
data_mode: ``provided`` for factual data, ``illustrative`` when charts
are intentionally demonstrative, or ``mixed``.
"""
normalized_action = (action or "").strip().lower()
if normalized_action == "catalog":
return json.dumps({"templates": [profile.to_dict() for profile in list_template_profiles()]}, ensure_ascii=False)
if normalized_action == "prepare":
return _prepare(
runtime,
theme=theme,
content_density=content_density,
required_features=required_features or [],
preferred_page_count=preferred_page_count,
selection_key=selection_key,
exclude_template_ids=exclude_template_ids or [],
template_id=template_id,
output_name=output_name,
page_brief=page_brief,
)
if normalized_action == "validate":
return _validate(
runtime,
file_path=file_path,
data_mode=data_mode,
expected_features=required_features or [],
)
raise ValueError("action 仅支持 catalog、prepare、validate。")
__all__ = ["page_report_template_tool"]
@@ -0,0 +1,194 @@
import logging
from pathlib import Path
from typing import Annotated
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
from langchain_core.messages import ToolMessage
from langgraph.config import get_config
from langgraph.types import Command
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
from deerflow.runtime.thread_paths import resolve_path_user_id
logger = logging.getLogger(__name__)
OUTPUTS_VIRTUAL_PREFIX = f"{VIRTUAL_PATH_PREFIX}/outputs"
# Maximum sibling filenames to list when reporting "file not found", to keep the
# tool message bounded — a chatty agent can fill up its outputs/ directory and
# we'd otherwise blow past the model's context window with the listing.
_MAX_AVAILABLE_FILE_HINTS = 25
def _get_thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str | None:
"""Resolve the current thread id from runtime context or RunnableConfig."""
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id:
return thread_id
runtime_config = getattr(runtime, "config", None) or {}
thread_id = runtime_config.get("configurable", {}).get("thread_id")
if thread_id:
return thread_id
try:
return get_config().get("configurable", {}).get("thread_id")
except RuntimeError:
return None
def _list_available_outputs(outputs_dir: Path) -> list[str]:
"""Return up to ``_MAX_AVAILABLE_FILE_HINTS`` files under ``outputs_dir``.
Used to build a "did you mean ..." hint when the model presents a file that
does not exist — a typo or a hallucinated filename was the most common
cause of "file not found" reports in production. Returns an empty list if
the directory itself does not exist or cannot be walked.
"""
if not outputs_dir.exists() or not outputs_dir.is_dir():
return []
try:
files: list[str] = []
for entry in sorted(outputs_dir.rglob("*"), key=lambda p: p.as_posix()):
if not entry.is_file():
continue
try:
rel = entry.relative_to(outputs_dir)
except ValueError:
continue
files.append(rel.as_posix())
if len(files) >= _MAX_AVAILABLE_FILE_HINTS:
break
return files
except OSError as exc:
logger.debug("Failed to enumerate %s: %s", outputs_dir, exc)
return []
def _normalize_presented_filepath(
runtime: ToolRuntime[ContextT, ThreadState],
filepath: str,
) -> str:
"""Normalize a presented file path to the `/mnt/user-data/outputs/*` contract.
Accepts either:
- A virtual sandbox path such as `/mnt/user-data/outputs/report.md`
- A host-side thread outputs path such as
`/app/backend/.deer-flow/threads/<thread>/user-data/outputs/report.md`
Returns:
The normalized virtual path.
Raises:
ValueError: If runtime metadata is missing, the path is outside the
current thread's outputs directory, or no file actually exists at
the resolved location. The error message lists existing files in
``outputs/`` so the agent can self-correct on its next turn
instead of leaving the user with a blank 404 in the UI.
"""
if runtime.state is None:
raise ValueError("Thread runtime state is not available")
thread_id = _get_thread_id(runtime)
if not thread_id:
raise ValueError("Thread ID is not available in runtime context or runtime config")
thread_data = runtime.state.get("thread_data") or {}
outputs_path = thread_data.get("outputs_path")
if not outputs_path:
raise ValueError("Thread outputs path is not available in runtime state")
outputs_dir = Path(outputs_path).resolve()
stripped = filepath.lstrip("/")
virtual_prefix = VIRTUAL_PATH_PREFIX.lstrip("/")
if stripped == virtual_prefix or stripped.startswith(virtual_prefix + "/"):
try:
actual_path = get_paths().resolve_virtual_path(thread_id, filepath, user_id=resolve_path_user_id(thread_id))
except TypeError:
actual_path = get_paths().resolve_virtual_path(thread_id, filepath)
else:
actual_path = Path(filepath).expanduser().resolve()
try:
relative_path = actual_path.relative_to(outputs_dir)
except ValueError as exc:
raise ValueError(f"Only files in {OUTPUTS_VIRTUAL_PREFIX} can be presented: {filepath}") from exc
# Existence + file-type check: the previous version trusted the agent
# blindly, so any typo or "I'll create it next turn" path produced a UI
# 404. Surfacing the failure here lets the model retry within the same
# turn and unblocks downstream `present_files` consumers.
if not actual_path.exists():
available = _list_available_outputs(outputs_dir)
if available:
hint = "; available files: " + ", ".join(available)
if len(available) >= _MAX_AVAILABLE_FILE_HINTS:
hint += f", ... (showing first {_MAX_AVAILABLE_FILE_HINTS})"
else:
hint = "; outputs/ is empty — write the file first"
raise ValueError(f"File does not exist: {filepath}{hint}")
if not actual_path.is_file():
raise ValueError(f"Path is not a regular file: {filepath}")
return f"{OUTPUTS_VIRTUAL_PREFIX}/{relative_path.as_posix()}"
@tool("present_files", parse_docstring=True)
def present_file_tool(
runtime: ToolRuntime[ContextT, ThreadState],
filepaths: list[str],
tool_call_id: Annotated[str, InjectedToolCallId],
) -> Command:
"""Make files visible to the user for viewing and rendering in the client interface.
When to use the present_files tool:
- Making any file available for the user to view, download, or interact with
- Presenting multiple related files at once
- After creating files that should be presented to the user
When NOT to use the present_files tool:
- When you only need to read file contents for your own processing
- For temporary or intermediate files not meant for user viewing
Notes:
- You should call this tool after creating files and moving them to the `/mnt/user-data/outputs` directory.
- This tool can be safely called in parallel with other tools. State updates are handled by a reducer to prevent conflicts.
Args:
filepaths: List of absolute file paths to present to the user. **Only** files in `/mnt/user-data/outputs` can be presented.
"""
# Per-file try/except so a single typo doesn't drop every other artefact
# the agent intended to present in the same turn — that pattern caused a
# lot of confusing "where did the file go?" reports in production.
normalized_paths: list[str] = []
failures: list[str] = []
for filepath in filepaths:
try:
normalized_paths.append(_normalize_presented_filepath(runtime, filepath))
except ValueError as exc:
failures.append(str(exc))
if not normalized_paths:
# Nothing succeeded: the agent must self-correct, so surface a
# tool-error message rather than silently writing an empty artifacts
# list (which the lead agent treats as "successfully presented").
message = "Error: " + " | ".join(failures) if failures else "Error: no files were presented"
return Command(update={"messages": [ToolMessage(message, tool_call_id=tool_call_id)]})
if failures:
message = "Successfully presented files: " + ", ".join(normalized_paths) + " | Skipped: " + " | ".join(failures)
else:
message = "Successfully presented files"
# The merge_artifacts reducer will handle merging and deduplication
return Command(
update={
"artifacts": normalized_paths,
"messages": [ToolMessage(message, tool_call_id=tool_call_id)],
},
)
@@ -0,0 +1,82 @@
"""read_peer_delivery —— 圆桌席位「按需读取前序席位**完整交付**」的只读工具。
背景:圆桌每个席位是独立 thread(独立 sandbox),彼此隔离。默认情况下,一个席位只能
从跨席位广播里看到前序席位的**截断摘要**(≤1500 字)。当席位识别到自己需要某个前序
席位的**全文**时,调用本工具按席位名取回完整交付。
数据来源:全文由**网关层**(``app.gateway``)在发起本席位 run 时,注入到
``runtime.context["roundtable_peer_deliveries"]`` —— 一个
``[{"name": <席位显示名>, "content": <完整交付正文>}, ...]`` 列表。本工具**只读该上下文
dict**,不跨 thread、不碰 sandbox、不发网络请求,因此完全在 ``deerflow.*`` 内(不违反
harness→app 导入防火墙)。非圆桌场景下该上下文为空,工具返回「无」。
「传摘要按需传全文」:完整交付**只在席位真正调用本工具时**才进入它的 LLM 上下文,平时
只有摘要,既省 token 又满足「需要时能拿全文」。详见
``frontend-web/docs/roundtable-dag-orchestration.md`` §12.9。
"""
from __future__ import annotations
import logging
from langchain.tools import ToolRuntime, tool
logger = logging.getLogger(__name__)
_CTX_KEY = "roundtable_peer_deliveries"
def _peer_deliveries(runtime: ToolRuntime | None) -> list[dict]:
"""从 runtime.context 取出网关注入的前序席位完整交付列表(缺失/非法时返回 [])。"""
if runtime is None:
return []
ctx = getattr(runtime, "context", None)
if not ctx:
return []
try:
peers = ctx.get(_CTX_KEY)
except Exception:
return []
if not isinstance(peers, list):
return []
return [p for p in peers if isinstance(p, dict)]
@tool("read_peer_delivery", parse_docstring=True)
def read_peer_delivery_tool(runtime: ToolRuntime, seat_name: str = "") -> str:
"""Read another roundtable seat's FULL deliverable on demand.
In a multi-agent roundtable you (a seat) normally only see **truncated
summaries** of earlier seats' deliverables. When you decide you genuinely
need the **complete text** of a specific earlier seat (e.g. to build on its
detailed data/conclusions), call this tool with that seat's name to fetch
its full deliverable. Prefer the summaries you already have; only call this
when the summary is insufficient.
Args:
seat_name: The earlier seat's display name (the Chinese name shown in
the summaries, e.g. "情报收集"). Leave empty to list which peers'
full deliverables are available to read.
"""
peers = _peer_deliveries(runtime)
if not peers:
return "(当前没有可读取的前序席位完整交付。请直接基于你已有的上下文与摘要完成交付。)"
names = [str(p.get("name") or "") for p in peers if p.get("name")]
query = (seat_name or "").strip()
if not query:
return (
"可读取**完整交付**的前序席位:" + "、".join(names) + "。\n"
"需要哪个席位的全文,就再次调用 read_peer_delivery 并把它的名称传给 seat_name。"
)
ql = query.lower()
# 精确匹配(忽略大小写)优先,其次子串互含(容忍模型给「情报收集席位」这类带后缀的名)。
for p in peers:
if str(p.get("name") or "").lower() == ql:
return str(p.get("content") or "(该席位交付为空。)")
for p in peers:
nm = str(p.get("name") or "")
if nm and (ql in nm.lower() or nm.lower() in ql):
return str(p.get("content") or "(该席位交付为空。)")
return f"未找到名为「{query}」的前序席位。可读取的有:" + "、".join(names) + "。"
@@ -0,0 +1,149 @@
"""Tool for managing user scheduled agent tasks."""
from __future__ import annotations
import json
from typing import Any, Literal
from langchain.tools import ToolRuntime, tool
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.runtime.scheduler import get_scheduled_task_service
from deerflow.runtime.user_context import get_current_user
def _runtime_context(runtime: ToolRuntime[ContextT, ThreadState]) -> dict[str, Any]:
context = getattr(runtime, "context", None)
merged = dict(context or {}) if isinstance(context, dict) else {}
config = getattr(runtime, "config", None)
if isinstance(config, dict):
configurable = config.get("configurable")
if isinstance(configurable, dict):
for key, value in configurable.items():
merged.setdefault(key, value)
return merged
@tool("scheduled_task", parse_docstring=True)
async def scheduled_task_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: Literal["create", "list", "update", "delete", "pause", "resume", "trigger"],
name: str | None = None,
schedule: str | None = None,
prompt: str | None = None,
task_id: str | None = None,
timezone: str | None = None,
enabled: bool | None = None,
execution_agent_name: str | None = None,
) -> str:
"""Create, list, update, delete, pause, resume, or trigger scheduled tasks.
Use this tool whenever the user asks to run something later or repeatedly,
such as daily reports, weekly inspections, reminders, audits, or recurring
research. Tasks can be created from any chat or custom agent. The scheduled
execution reuses the current custom agent by default, including its skills
and tool groups, but the final output is delivered to the user's dedicated
scheduled-task conversation.
Args:
action: Operation to perform: create, list, update, delete, pause, resume, or trigger.
name: Human-friendly task name. Required for create.
schedule: Natural language schedule or cron expression. Examples: "every day at 9am", "每天9点", "0 9 * * *".
prompt: The instruction to run on schedule. Required for create.
task_id: Existing task id for update, delete, pause, resume, or trigger.
timezone: IANA timezone, e.g. "Asia/Shanghai". Defaults to UTC if omitted.
enabled: Whether the task is enabled when updating.
execution_agent_name: Optional custom agent name to run this task with. Defaults to the current agent.
"""
user = get_current_user()
if user is None:
return "Error: scheduled tasks require an authenticated user."
ctx = _runtime_context(runtime)
if ctx.get("is_scheduled_run"):
return "Error: scheduled task management is disabled while a scheduled task is running."
service = get_scheduled_task_service()
user_id = str(user.id)
current_agent = ctx.get("agent_name")
if not isinstance(current_agent, str):
current_agent = None
try:
if action == "list":
tasks = await service.list_tasks(user_id)
return json.dumps({"tasks": tasks}, ensure_ascii=False, default=str)
if action == "create":
if not prompt or not prompt.strip():
return "Error: prompt is required when creating a scheduled task."
if not schedule or not schedule.strip():
return "Error: schedule is required when creating a scheduled task."
execution_context = {
key: value
for key, value in ctx.items()
if key
in {
"agent_name",
"model_name",
"mode",
"thinking_enabled",
"reasoning_effort",
"is_plan_mode",
"subagent_enabled",
"max_concurrent_subagents",
}
}
task = await service.create_task(
user_id=user_id,
name=(name or "Scheduled task").strip(),
prompt=prompt,
schedule=schedule,
timezone=timezone,
source_thread_id=ctx.get("thread_id") if isinstance(ctx.get("thread_id"), str) else None,
source_agent_name=current_agent,
execution_agent_name=execution_agent_name or current_agent,
execution_context=execution_context,
)
return json.dumps({"created": True, "task": task}, ensure_ascii=False, default=str)
if not task_id:
return f"Error: task_id is required for action={action}."
if action == "update":
update: dict[str, Any] = {}
if name is not None:
update["name"] = name
if prompt is not None:
update["prompt"] = prompt
if schedule is not None:
update["schedule"] = schedule
if timezone is not None:
update["timezone"] = timezone
if enabled is not None:
update["enabled"] = enabled
if execution_agent_name is not None:
update["execution_agent_name"] = execution_agent_name
task = await service.update_task(user_id, task_id, update)
return json.dumps({"updated": task is not None, "task": task}, ensure_ascii=False, default=str)
if action == "delete":
deleted = await service.delete_task(user_id, task_id)
return json.dumps({"deleted": deleted}, ensure_ascii=False)
if action == "pause":
task = await service.pause_task(user_id, task_id)
return json.dumps({"paused": task is not None, "task": task}, ensure_ascii=False, default=str)
if action == "resume":
task = await service.resume_task(user_id, task_id)
return json.dumps({"resumed": task is not None, "task": task}, ensure_ascii=False, default=str)
if action == "trigger":
task = await service.trigger_task(user_id, task_id)
return json.dumps({"triggered": task is not None, "task": task}, ensure_ascii=False, default=str)
except Exception as exc:
return f"Error: failed to manage scheduled task: {exc}"
return f"Error: unsupported action={action}."
@@ -0,0 +1,75 @@
import logging
import yaml
from langchain_core.messages import ToolMessage
from langchain_core.tools import tool
from langgraph.prebuilt import ToolRuntime
from langgraph.types import Command
from deerflow.config.agents_config import validate_agent_id
from deerflow.config.paths import get_paths
logger = logging.getLogger(__name__)
@tool
def setup_agent(
soul: str,
description: str,
runtime: ToolRuntime,
name: str | None = None,
skills: list[str] | None = None,
) -> Command:
"""Setup the custom DeerFlow agent.
Args:
soul: Full SOUL.md content defining the agent's personality and behavior.
description: One-line description of what the agent does.
name: Optional human-readable display name for the agent. If omitted,
the agent's stable id is used as the display name.
skills: Optional list of skill names this agent should use. None or empty means no skills. Maximum 5 skills allowed.
"""
agent_name: str | None = (runtime.context.get("agent_id") or runtime.context.get("agent_name")) if runtime.context else None
agent_dir = None
is_new_dir = False
try:
agent_name = validate_agent_id(agent_name)
paths = get_paths()
agent_dir = paths.agent_dir(agent_name) if agent_name else paths.base_dir
is_new_dir = not agent_dir.exists()
agent_dir.mkdir(parents=True, exist_ok=True)
if agent_name:
# If agent_name is provided, we are creating a custom agent in the agents/ directory
display_name = (name or "").strip() or agent_name
config_data: dict = {"id": agent_name, "name": display_name}
if description:
config_data["description"] = description
if skills is not None:
config_data["skills"] = skills[:5]
config_file = agent_dir / "config.yaml"
with open(config_file, "w", encoding="utf-8") as f:
yaml.dump(config_data, f, default_flow_style=False, allow_unicode=True)
soul_file = agent_dir / "SOUL.md"
soul_file.write_text(soul, encoding="utf-8")
logger.info(f"[agent_creator] Created agent '{agent_name}' at {agent_dir}")
return Command(
update={
"created_agent_name": agent_name,
"messages": [ToolMessage(content=f"Agent '{agent_name}' created successfully!", tool_call_id=runtime.tool_call_id)],
}
)
except Exception as e:
import shutil
if agent_name and is_new_dir and agent_dir is not None and agent_dir.exists():
# Cleanup the custom agent directory only if it was newly created during this call
shutil.rmtree(agent_dir)
logger.error(f"[agent_creator] Failed to create agent '{agent_name}': {e}", exc_info=True)
return Command(update={"messages": [ToolMessage(content=f"Error: {e}", tool_call_id=runtime.tool_call_id)]})
@@ -0,0 +1,55 @@
"""报告结构「智能新增」用的提交工具。
与 ``setup_writing`` 同构:模型在几轮对话里问清用户想要的报告结构后,调用本工具把建议字段
「提交」出来。实际总是被 ``SetupReportStructureApprovalMiddleware`` 在 ``after_model``
拦截(不真正执行)——拦截后把字段打包进审批 ToolMessage,前端据此回填右侧表单。
函数体只是兜底:万一未被拦截,也只回一句确认、不落任何盘。
"""
from __future__ import annotations
import logging
from langchain_core.messages import ToolMessage
from langchain_core.tools import tool
from langgraph.prebuilt import ToolRuntime
from langgraph.types import Command
logger = logging.getLogger(__name__)
@tool
def setup_report_structure(
title: str,
content: str,
runtime: ToolRuntime,
name: str | None = None,
structure_mode: str | None = None,
retrieval_directions: list[str] | None = None,
retrieval_skills: list[str] | None = None,
) -> Command:
"""把与用户聊清的报告结构配置提交给前端表单(不直接入库)。
Args:
title: 报告结构标题(必填,短、可展示,如「市场分析报告模板」)。
content: **已与用户确认的报告大纲全文**,使用 Markdown 标题层级
(`#` / `##` / `###`),只写结构与小节要点,不写正文。
name: 一句话描述这套结构的适用场景(可选)。
structure_mode: 结构约束。``fixed`` = 固定大纲(按章节逐一成文,不得改写/合并/省略);
``adaptive`` = 弹性大纲(可按材料合并或省略无依据小节)。不确定时用 ``adaptive``。
retrieval_directions: 检索方向列表(可选)。每项是一个拆词维度,例如「各品牌汽车销量」,
**不是**直接拿去搜索的关键词。用户没提就留空。
retrieval_skills: 检索来源技能 name 列表(可选,hyphen-case 文件夹 id)。
只填用户明确点名、且出现在系统给定技能列表里的项;不确定就留空,交给用户在表单里选。
"""
logger.info("[setup_report_structure] proposed config submitted (intercepted by approval middleware)")
return Command(
update={
"messages": [
ToolMessage(
content="报告结构已生成,请在对话里确认后应用到右侧表单,再点保存。",
tool_call_id=runtime.tool_call_id,
)
]
}
)
@@ -0,0 +1,59 @@
"""写作配置助手用的提交工具。
与 ``setup_agent`` 同构:模型在「写作配置 Q&A」里与用户聊清需求后,调用本工具把建议的
写作配置「提交」出来。实际它总是被 ``SetupWritingApprovalMiddleware`` 在 ``after_model``
拦截(不真正执行)——拦截后把建议字段打包进审批 ToolMessage,前端据此回填左侧写作表单。
因此本工具的函数体基本是兜底:万一未被拦截(如审批被预先放行),也只回一句确认、不落任何盘。
"""
from __future__ import annotations
import logging
from langchain_core.messages import ToolMessage
from langchain_core.tools import tool
from langgraph.prebuilt import ToolRuntime
from langgraph.types import Command
logger = logging.getLogger(__name__)
@tool
def setup_writing(
user_intent: str,
runtime: ToolRuntime,
article_type: str | None = None,
word_count_target: int | None = None,
target_audience: str | None = None,
writing_mode: str | None = None,
material_source: str | None = None,
outline: str | None = None,
article_type_detail: str | None = None,
) -> Command:
"""把与用户聊清的写作配置提交给前端表单(不直接开始写作)。
Args:
user_intent: 用户的写作意图(精炼成一句话的写作目标)。
article_type: 文章类型。优先填系统给定的合法类型 key;若已有类型都不贴切,可**自拟一个新的
文章类型**——此时填一个简短的中文类型名(如「政策解读」「人物特写」),并在
``article_type_detail`` 里说明该类型特征。不确定可留空。
word_count_target: 目标字数(正整数)。
target_audience: 目标读者(如「行业专家」「普通读者」)。
writing_mode: 写作模式,'strict'(严格依据素材)或 'loose'(可结合通用知识)。
material_source: 素材来源,'knowledge_base'(知识库)或 'skill'(技能检索)。
outline: **已与用户确认的大纲全文**(保留其层级与标题)。本工具在用户确认大纲后调用,
故通常应带上这份大纲;用户未提供/未确认大纲时才留空。
article_type_detail: 仅当 ``article_type`` 是**新类型(不在已有列表里)**时填写:用一句话说明
这个类型的写作侧重/特征(如「以政策原文为锚、逐条拆解影响并给出执行建议」)。命中已有类型时留空。
"""
logger.info("[setup_writing] proposed writing config submitted (intercepted by approval middleware)")
return Command(
update={
"messages": [
ToolMessage(
content="写作配置已生成,请在右侧确认后应用到表单,或直接开始写作。",
tool_call_id=runtime.tool_call_id,
)
]
}
)
@@ -0,0 +1,390 @@
"""skill_view and skill_list — read-only tools for agent skill introspection."""
from __future__ import annotations
import json
import logging
from langchain.tools import ToolRuntime, tool
logger = logging.getLogger(__name__)
_ROUNDTABLE_COORDINATOR_AGENT_ID = "roundtable-coordinator"
COORDINATOR_ONLY_SKILL_NAMES = frozenset({"agent_orchestration", "agent-orchestration"})
def can_access_coordinator_only_skill(agent_id: str | None, skill_name: str) -> bool:
"""Return whether this runtime identity may discover/read a reserved orchestration skill."""
normalized = (skill_name or "").strip().lower()
return normalized not in COORDINATOR_ONLY_SKILL_NAMES or agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID
def is_coordinator_only_skill_path(path: str) -> bool:
"""Recognize reserved skill directories in virtual/container paths."""
parts = {part.strip().lower() for part in (path or "").replace("\\", "/").split("/") if part}
return bool(parts & COORDINATOR_ONLY_SKILL_NAMES)
def _resolve_active_agent_id(runtime: ToolRuntime | None) -> str | None:
"""Extract the agent_id under which the current tool call is running.
Custom agents pass their id via either the ``context`` dict or the
``configurable`` section of the LangGraph runtime config. The default
lead agent runs without an explicit agent_id — callers should treat
a None return as "no per-agent skills filter applies".
"""
if runtime is None:
return None
try:
if getattr(runtime, "context", None):
ctx_id = runtime.context.get("agent_id") or runtime.context.get("agent_name")
if ctx_id:
return str(ctx_id)
cfg = getattr(runtime, "config", None)
if isinstance(cfg, dict):
configurable = cfg.get("configurable", {})
cid = configurable.get("agent_id") or configurable.get("agent_name")
if cid:
return str(cid)
except Exception:
return None
return None
def _load_agent_skill_whitelist(agent_id: str | None, extra_skills: list[str] | None = None) -> set[str] | None:
"""Return the explicit skill name set declared in an agent's config.yaml.
Semantics:
- ``None`` returned → no agent_id, or the agent's on-disk config is
missing entirely — caller should fall back to "all skills visible"
(default lead agent behavior).
- ``set()`` (empty) → custom agent with ``skills: []`` declared **or**
with no ``skills`` key at all — visibility is intentionally empty.
This mirrors the prompt layer (``agents_config.AgentConfig.skills``:
``None``/``[]`` both mean "no skills" for custom agents), so an agent
whose config omits ``skills`` can no longer enumerate every skill
through this tool.
- Non-empty set → only these names are visible to this agent.
``extra_skills`` only widens the **deep-research collector** allowlist
for one run (report-structure 检索来源). Other agents ignore it.
"""
if not agent_id:
return None
try:
from deerflow.config.agents_config import load_agent_config
cfg = load_agent_config(agent_id)
if cfg is None:
return None
allowed = {
name
for name in (cfg.skills or [])
if can_access_coordinator_only_skill(agent_id, name)
}
except Exception:
logger.debug("Failed to load agent config for skill_list filter", exc_info=True)
return None
if extra_skills:
from deerflow.agents.deep_research.retrieval import merge_collector_skill_allowlist
merged = merge_collector_skill_allowlist(agent_id, list(allowed), extra_skills)
return set(merged or [])
return allowed
def _resolve_extra_skills(runtime: ToolRuntime | None) -> list[str]:
"""Extra skill names from this run's context (collector 检索来源)."""
if runtime is None:
return []
try:
from deerflow.agents.deep_research.retrieval import runtime_extra_skills
if getattr(runtime, "context", None):
extras = runtime_extra_skills(runtime.context)
if extras:
return extras
cfg = getattr(runtime, "config", None)
if isinstance(cfg, dict):
return runtime_extra_skills(cfg.get("configurable", {}) or {})
except Exception:
return []
return []
def _resolve_effective_user_id() -> str | None:
"""当前请求/线程绑定的用户 id;解析失败时返回 None。"""
try:
from deerflow.runtime.user_context import get_effective_user_id
return get_effective_user_id()
except Exception:
logger.debug("Failed to resolve effective user id for skill_list", exc_info=True)
return None
def _load_owned_skill_names(user_id: str | None) -> set[str] | None:
"""返回 ``owner_user_id == user_id`` 的自定义技能名集合。
用于默认 lead agent 的可见性过滤:只算"用户自己拥有的"自定义技能,不含
其他用户发布的。返回 ``None`` 表示 ``SkillStore`` 不可用(未配置数据库
等)—— 调用方应降级为"放行全部自定义技能",避免离线无库部署下技能凭空
消失。
"""
if not user_id:
return None
try:
from deerflow.persistence.engine import get_session_factory, run_db_blocking
from deerflow.persistence.skills import make_skill_store
factory = get_session_factory()
if factory is None:
return None
store = make_skill_store(factory)
records = run_db_blocking(store.list_visible(user_id))
return {r["name"] for r in records if r.get("owner_user_id") == user_id}
except Exception:
logger.debug("Failed to load owned skill names for skill_list filter", exc_info=True)
return None
def skill_view_impl(name: str, agent_id: str | None, extra_skills: list[str] | None = None) -> str:
"""Read a skill's SKILL.md, honoring the agent's config.yaml whitelist.
Custom agents may only read skills on their whitelist — same filter as
``skill_list``, so a restricted agent cannot bypass its allowlist by
guessing skill names. Replies "not found" rather than "forbidden" to
avoid leaking which skills exist.
"""
if not can_access_coordinator_only_skill(agent_id, name):
return f"Skill '{name}' not found."
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.usage import bump_view
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
if allowed is not None and name not in allowed:
return f"Skill '{name}' not found."
storage = get_or_new_skill_storage()
try:
if storage.custom_skill_exists(name):
content = storage.read_custom_skill(name)
elif storage.public_skill_exists(name):
skill_file = storage.get_skills_root_path()
from pathlib import Path
from deerflow.skills.types import SKILL_MD_FILE
path = Path(skill_file) / "public" / name / SKILL_MD_FILE
if not path.exists():
return f"Skill '{name}' not found."
content = path.read_text(encoding="utf-8")
else:
return f"Skill '{name}' not found."
except Exception as e:
logger.debug("skill_view failed for %r: %s", name, e)
return f"Error reading skill '{name}': {e}"
try:
bump_view(name)
except Exception:
pass
return content
@tool("skill_view")
def skill_view_tool(name: str, runtime: ToolRuntime) -> str:
"""Read the full SKILL.md content of a skill by name.
Args:
name: The skill name (hyphen-case, e.g. 'my-skill').
"""
return skill_view_impl(name, _resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
def _resolve_skills_container_base_path() -> str:
"""容器内技能挂载根路径(用于回传 location,供 agent read_file)。"""
try:
from deerflow.config import get_app_config
return get_app_config().skills.container_path
except Exception:
return "/mnt/skills"
def _score_skill(query_terms: list[str], haystack: str) -> int:
"""对单个技能按关键词命中计分(纯关键词、离线、确定性)。"""
score = 0
for term in query_terms:
if term and term in haystack:
score += 1
return score
def search_skills_impl(query: str, agent_id: str | None, top_n: int = 5, extra_skills: list[str] | None = None) -> str:
"""按关键词检索可用技能,返回 top-N 的 name/description/category/location。
与 ``skill_list`` 共享可见性过滤(自定义 agent 走白名单;默认 lead agent 只
暴露未归档且内置或属于当前用户的技能),并只检索**已启用**的技能 —— 它是
"技能压缩"开启后,agent 调出被压缩(非常驻)技能的主要入口。匹配字段为技能
名与描述。
"""
import re
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.types import SkillCategory
from deerflow.skills.usage import STATE_ARCHIVED, all_entries
query = (query or "").strip()
if not query:
return "search_skills: empty query. Provide a short keyword query describing the task."
terms = [t for t in re.findall(r"\w+", query.lower()) if t]
# 整串也作为一个匹配项,兼顾中文等不被 \w+ 切分出有意义 token 的查询。
whole = query.lower()
if whole and whole not in terms:
terms.append(whole)
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
owned: set[str] | None = None
if allowed is None:
owned = _load_owned_skill_names(_resolve_effective_user_id())
try:
top_n = max(1, min(int(top_n or 5), 50))
except (TypeError, ValueError):
top_n = 5
try:
storage = get_or_new_skill_storage()
skills = storage.load_skills(enabled_only=True)
usage = all_entries()
base_path = _resolve_skills_container_base_path()
scored: list[tuple[int, dict]] = []
for skill in skills:
if not can_access_coordinator_only_skill(agent_id, skill.name):
continue
entry = usage.get(skill.name, {})
if allowed is not None:
if skill.name not in allowed:
continue
else:
if entry.get("state") == STATE_ARCHIVED:
continue
if skill.category == SkillCategory.CUSTOM and owned is not None and skill.name not in owned:
continue
haystack = f"{skill.name} {skill.description}".lower()
score = _score_skill(terms, haystack)
if score <= 0:
continue
scored.append((
score,
{
"name": skill.name,
"description": skill.description,
"category": skill.category.value if hasattr(skill.category, "value") else str(skill.category),
"location": skill.get_container_file_path(base_path),
},
))
scored.sort(key=lambda x: x[0], reverse=True)
results = [item for _, item in scored[:top_n]]
if not results:
return f"No skills matched '{query}'. Try a broader keyword, or call skill_list to browse everything available."
return json.dumps(results, ensure_ascii=False, indent=2)
except Exception as e:
logger.debug("search_skills failed: %s", e)
return f"Error searching skills: {e}"
@tool("search_skills")
def search_skills_tool(query: str, runtime: ToolRuntime) -> str:
"""Search available skills by keyword and return the best matches.
Use this to discover skills that are not already described in full in your
system prompt. Returns a JSON array of matches, each with `name`,
`description`, `category`, and `location` — then `read_file` the `location`
of the most relevant match and follow its SKILL.md instructions.
Args:
query: A short keyword query describing the task (e.g. 'pdf table extract').
"""
return search_skills_impl(query, _resolve_active_agent_id(runtime), extra_skills=_resolve_extra_skills(runtime))
@tool("skill_list")
def skill_list_tool(runtime: ToolRuntime) -> str:
"""List skills available to this agent, with metadata and usage stats.
Does NOT read SKILL.md content.
For a **custom agent**, the result is filtered to skills explicitly
declared in the agent's ``.deer-flow/agents/{agent_id}/config.yaml``
under the ``skills:`` field — the agent only sees what it was wired to
use.
For the **default lead agent** (no agent_id in runtime), the result is
filtered to non-archived skills that are either built-in (public) or
owned by the current user. Other users' published custom skills and
archived skills are excluded.
Returns a JSON array with fields: name, description, category, enabled,
state, use_count, view_count, patch_count, last_activity_at, pinned,
source.
"""
return skill_list_impl(_resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
def skill_list_impl(agent_id: str | None, extra_skills: list[str] | None = None) -> str:
"""List skills visible to ``agent_id`` (None = default lead agent)."""
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.types import SkillCategory
from deerflow.skills.usage import STATE_ARCHIVED, all_entries, latest_activity_at
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
# 默认 lead agent 没有 per-agent 白名单 —— 改为只暴露"未归档"且"内置或属于
# 当前用户"的技能。owned 为 None 表示 SkillStore 不可用,降级放行全部自定义
# 技能(见 _load_owned_skill_names)。
owned: set[str] | None = None
if allowed is None:
owned = _load_owned_skill_names(_resolve_effective_user_id())
try:
storage = get_or_new_skill_storage()
skills = storage.load_skills(enabled_only=False)
usage = all_entries()
result = []
for skill in skills:
if not can_access_coordinator_only_skill(agent_id, skill.name):
continue
entry = usage.get(skill.name, {})
if allowed is not None:
# 自定义 agent:严格按 config.yaml 的 skills 白名单过滤。
if skill.name not in allowed:
continue
else:
# 默认 agent:跳过已归档技能。
if entry.get("state") == STATE_ARCHIVED:
continue
# 自定义技能仅当属于当前用户时可见;内置 public 技能始终可见。
if skill.category == SkillCategory.CUSTOM and owned is not None and skill.name not in owned:
continue
result.append({
"name": skill.name,
"description": skill.description,
"category": skill.category.value if hasattr(skill.category, "value") else str(skill.category),
"enabled": skill.enabled,
"state": entry.get("state", "active"),
"use_count": entry.get("use_count", 0),
"view_count": entry.get("view_count", 0),
"patch_count": entry.get("patch_count", 0),
"last_activity_at": latest_activity_at(skill.name),
"pinned": entry.get("pinned", False),
"source": entry.get("source", "upload"),
})
return json.dumps(result, ensure_ascii=False, indent=2)
except Exception as e:
logger.debug("skill_list failed: %s", e)
return f"Error listing skills: {e}"
@@ -0,0 +1,308 @@
"""Task tool for delegating work to subagents."""
import asyncio
import logging
import uuid
from dataclasses import replace
from typing import TYPE_CHECKING, Annotated, Any, cast
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
from langgraph.config import get_stream_writer
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config import get_app_config
from deerflow.sandbox.security import LOCAL_BASH_SUBAGENT_DISABLED_MESSAGE, is_host_bash_allowed
from deerflow.subagents import SubagentExecutor, get_available_subagent_names, get_subagent_config
from deerflow.subagents.config import resolve_subagent_model_name
from deerflow.subagents.executor import (
SubagentStatus,
cleanup_background_task,
get_background_task_result,
request_cancel_background_task,
)
if TYPE_CHECKING:
from deerflow.config.app_config import AppConfig
logger = logging.getLogger(__name__)
def _get_runtime_app_config(runtime: Any) -> "AppConfig | None":
context = getattr(runtime, "context", None)
if isinstance(context, dict):
app_config = context.get("app_config")
if app_config is not None:
return cast("AppConfig", app_config)
return None
def _merge_skill_allowlists(parent: list[str] | None, child: list[str] | None) -> list[str] | None:
"""Return the effective subagent skill allowlist under the parent policy."""
if parent is None:
return child
if child is None:
return list(parent)
parent_set = set(parent)
return [skill for skill in child if skill in parent_set]
@tool("task", parse_docstring=True)
async def task_tool(
runtime: ToolRuntime[ContextT, ThreadState],
description: str,
prompt: str,
subagent_type: str,
tool_call_id: Annotated[str, InjectedToolCallId],
max_turns: int | None = None,
) -> str:
"""Delegate a task to a specialized subagent that runs in its own context.
Subagents help you:
- Preserve context by keeping exploration and implementation separate
- Handle complex multi-step tasks autonomously
- Execute commands or operations in isolated contexts
Built-in subagent types:
- **general-purpose**: A capable agent for complex, multi-step tasks that require
both exploration and action. Use when the task requires complex reasoning,
multiple dependent steps, or would benefit from isolated context.
- **bash**: Command execution specialist for running bash commands. This is only
available when host bash is explicitly allowed or when using an isolated shell
sandbox such as `AioSandboxProvider`.
Additional custom subagent types may be defined in config.yaml under
`subagents.custom_agents`. Each custom type can have its own system prompt,
tools, skills, model, and timeout configuration. If an unknown subagent_type
is provided, the error message will list all available types.
When to use this tool:
- Complex tasks requiring multiple steps or tools
- Tasks that produce verbose output
- When you want to isolate context from the main conversation
- Parallel research or exploration tasks
When NOT to use this tool:
- Simple, single-step operations (use tools directly)
- Tasks requiring user interaction or clarification
Args:
description: A short (3-5 word) description of the task for logging/display. ALWAYS PROVIDE THIS PARAMETER FIRST.
prompt: The task description for the subagent. Be specific and clear about what needs to be done. ALWAYS PROVIDE THIS PARAMETER SECOND.
subagent_type: The type of subagent to use. ALWAYS PROVIDE THIS PARAMETER THIRD.
max_turns: Optional maximum number of agent turns. Defaults to subagent's configured max.
"""
runtime_app_config = _get_runtime_app_config(runtime)
available_subagent_names = get_available_subagent_names(app_config=runtime_app_config) if runtime_app_config is not None else get_available_subagent_names()
# Get subagent configuration
config = get_subagent_config(subagent_type, app_config=runtime_app_config) if runtime_app_config is not None else get_subagent_config(subagent_type)
if config is None:
available = ", ".join(available_subagent_names)
return f"Error: Unknown subagent type '{subagent_type}'. Available: {available}"
if subagent_type == "bash":
host_bash_allowed = is_host_bash_allowed(runtime_app_config) if runtime_app_config is not None else is_host_bash_allowed()
if not host_bash_allowed:
return f"Error: {LOCAL_BASH_SUBAGENT_DISABLED_MESSAGE}"
# Build config overrides
overrides: dict = {}
# Skills are loaded by SubagentExecutor per-session (aligned with Codex's pattern:
# each subagent loads its own skills based on config, injected as conversation items).
# No longer appended to system_prompt here.
if max_turns is not None:
overrides["max_turns"] = max_turns
# Extract parent context from runtime
sandbox_state = None
thread_data = None
thread_id = None
parent_model = None
trace_id = None
metadata: dict = {}
if runtime is not None:
sandbox_state = runtime.state.get("sandbox")
thread_data = runtime.state.get("thread_data")
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id is None:
thread_id = runtime.config.get("configurable", {}).get("thread_id")
# Try to get parent model from configurable
metadata = runtime.config.get("metadata", {})
parent_model = metadata.get("model_name")
# Get or generate trace_id for distributed tracing
trace_id = metadata.get("trace_id") or str(uuid.uuid4())[:8]
parent_available_skills = metadata.get("available_skills")
if parent_available_skills is not None:
overrides["skills"] = _merge_skill_allowlists(list(parent_available_skills), config.skills)
if overrides:
config = replace(config, **overrides)
# Get available tools (excluding task tool to prevent nesting)
# Lazy import to avoid circular dependency
from deerflow.tools import get_available_tools
# Inherit parent agent's tool_groups so subagents respect the same restrictions
parent_tool_groups = metadata.get("tool_groups")
resolved_app_config = runtime_app_config
if config.model == "inherit" and parent_model is None and resolved_app_config is None:
resolved_app_config = get_app_config()
effective_model = resolve_subagent_model_name(config, parent_model, app_config=resolved_app_config)
# Subagents should not have subagent tools enabled (prevent recursive nesting)
available_tools_kwargs = {
"model_name": effective_model,
"groups": parent_tool_groups,
"subagent_enabled": False,
}
if resolved_app_config is not None:
available_tools_kwargs["app_config"] = resolved_app_config
tools = get_available_tools(**available_tools_kwargs)
# Create executor
executor_kwargs = {
"config": config,
"tools": tools,
"parent_model": parent_model,
"sandbox_state": sandbox_state,
"thread_data": thread_data,
"thread_id": thread_id,
"trace_id": trace_id,
}
if resolved_app_config is not None:
executor_kwargs["app_config"] = resolved_app_config
executor = SubagentExecutor(**executor_kwargs)
# Start background execution (always async to prevent blocking)
# Use tool_call_id as task_id for better traceability
task_id = executor.execute_async(prompt, task_id=tool_call_id)
# Poll for task completion in backend (removes need for LLM to poll)
poll_count = 0
last_status = None
last_message_count = 0 # Track how many AI messages we've already sent
# Polling timeout: execution timeout + 60s buffer, checked every 5s
max_poll_count = (config.timeout_seconds + 60) // 5
logger.info(f"[trace={trace_id}] Started background task {task_id} (subagent={subagent_type}, timeout={config.timeout_seconds}s, polling_limit={max_poll_count} polls)")
writer = get_stream_writer()
# Send Task Started message'
writer({"type": "task_started", "task_id": task_id, "description": description})
try:
while True:
result = get_background_task_result(task_id)
if result is None:
logger.error(f"[trace={trace_id}] Task {task_id} not found in background tasks")
writer({"type": "task_failed", "task_id": task_id, "error": "Task disappeared from background tasks"})
cleanup_background_task(task_id)
return f"Error: Task {task_id} disappeared from background tasks"
# Log status changes for debugging
if result.status != last_status:
logger.info(f"[trace={trace_id}] Task {task_id} status: {result.status.value}")
last_status = result.status
# Check for new AI messages and send task_running events
ai_messages = result.ai_messages or []
current_message_count = len(ai_messages)
if current_message_count > last_message_count:
# Send task_running event for each new message
for i in range(last_message_count, current_message_count):
message = ai_messages[i]
writer(
{
"type": "task_running",
"task_id": task_id,
"message": message,
"message_index": i + 1, # 1-based index for display
"total_messages": current_message_count,
}
)
logger.info(f"[trace={trace_id}] Task {task_id} sent message #{i + 1}/{current_message_count}")
last_message_count = current_message_count
# Check if task completed, failed, or timed out
if result.status == SubagentStatus.COMPLETED:
writer({"type": "task_completed", "task_id": task_id, "result": result.result})
logger.info(f"[trace={trace_id}] Task {task_id} completed after {poll_count} polls")
cleanup_background_task(task_id)
return f"Task Succeeded. Result: {result.result}"
elif result.status == SubagentStatus.FAILED:
writer({"type": "task_failed", "task_id": task_id, "error": result.error})
logger.error(f"[trace={trace_id}] Task {task_id} failed: {result.error}")
cleanup_background_task(task_id)
return f"Task failed. Error: {result.error}"
elif result.status == SubagentStatus.CANCELLED:
writer({"type": "task_cancelled", "task_id": task_id, "error": result.error})
logger.info(f"[trace={trace_id}] Task {task_id} cancelled: {result.error}")
cleanup_background_task(task_id)
return "Task cancelled by user."
elif result.status == SubagentStatus.TIMED_OUT:
writer({"type": "task_timed_out", "task_id": task_id, "error": result.error})
logger.warning(f"[trace={trace_id}] Task {task_id} timed out: {result.error}")
cleanup_background_task(task_id)
return f"Task timed out. Error: {result.error}"
# Still running, wait before next poll
await asyncio.sleep(5)
poll_count += 1
# Polling timeout as a safety net (in case thread pool timeout doesn't work)
# Set to execution timeout + 60s buffer, in 5s poll intervals
# This catches edge cases where the background task gets stuck
# Note: We don't call cleanup_background_task here because the task may
# still be running in the background. The cleanup will happen when the
# executor completes and sets a terminal status.
if poll_count > max_poll_count:
timeout_minutes = config.timeout_seconds // 60
logger.error(f"[trace={trace_id}] Task {task_id} polling timed out after {poll_count} polls (should have been caught by thread pool timeout)")
writer({"type": "task_timed_out", "task_id": task_id})
return f"Task polling timed out after {timeout_minutes} minutes. This may indicate the background task is stuck. Status: {result.status.value}"
except asyncio.CancelledError:
# Signal the background subagent thread to stop cooperatively.
# Without this, the thread (running in ThreadPoolExecutor with its
# own event loop via asyncio.run) would continue executing even
# after the parent task is cancelled.
request_cancel_background_task(task_id)
async def cleanup_when_done() -> None:
max_cleanup_polls = max_poll_count
cleanup_poll_count = 0
while True:
result = get_background_task_result(task_id)
if result is None:
return
if result.status in {SubagentStatus.COMPLETED, SubagentStatus.FAILED, SubagentStatus.CANCELLED, SubagentStatus.TIMED_OUT} or getattr(result, "completed_at", None) is not None:
cleanup_background_task(task_id)
return
if cleanup_poll_count > max_cleanup_polls:
logger.warning(f"[trace={trace_id}] Deferred cleanup for task {task_id} timed out after {cleanup_poll_count} polls")
return
await asyncio.sleep(5)
cleanup_poll_count += 1
def log_cleanup_failure(cleanup_task: asyncio.Task[None]) -> None:
if cleanup_task.cancelled():
return
exc = cleanup_task.exception()
if exc is not None:
logger.error(f"[trace={trace_id}] Deferred cleanup failed for task {task_id}: {exc}")
logger.debug(f"[trace={trace_id}] Scheduling deferred cleanup for cancelled task {task_id}")
asyncio.create_task(cleanup_when_done()).add_done_callback(log_cleanup_failure)
raise
@@ -0,0 +1,202 @@
"""Tool search — deferred tool discovery at runtime.
Contains:
- DeferredToolRegistry: stores deferred tools and handles regex search
- tool_search: the LangChain tool the agent calls to discover deferred tools
The agent sees deferred tool names in <available-deferred-tools> but cannot
call them until it fetches their full schema via the tool_search tool.
Source-agnostic: no mention of MCP or tool origin.
"""
import contextvars
import json
import logging
import re
from dataclasses import dataclass
from langchain.tools import BaseTool
from langchain_core.tools import tool
from langchain_core.utils.function_calling import convert_to_openai_function
logger = logging.getLogger(__name__)
MAX_RESULTS = 5 # Max tools returned per search
# ── Registry ──
@dataclass
class DeferredToolEntry:
"""Lightweight metadata for a deferred tool (no full schema in context)."""
name: str
description: str
tool: BaseTool # Full tool object, returned only on search match
class DeferredToolRegistry:
"""Registry of deferred tools, searchable by regex pattern."""
def __init__(self):
self._entries: list[DeferredToolEntry] = []
def register(self, tool: BaseTool) -> None:
self._entries.append(
DeferredToolEntry(
name=tool.name,
description=tool.description or "",
tool=tool,
)
)
def promote(self, names: set[str]) -> None:
"""Remove tools from the deferred registry so they pass through the filter.
Called after tool_search returns a tool's schema — the LLM now knows
the full definition, so the DeferredToolFilterMiddleware should stop
stripping it from bind_tools on subsequent calls.
"""
if not names:
return
before = len(self._entries)
self._entries = [e for e in self._entries if e.name not in names]
promoted = before - len(self._entries)
if promoted:
logger.debug(f"Promoted {promoted} tool(s) from deferred to active: {names}")
def search(self, query: str) -> list[BaseTool]:
"""Search deferred tools by regex pattern against name + description.
Supports three query forms (aligned with Claude Code):
- "select:name1,name2" — exact name match
- "+keyword rest" — name must contain keyword, rank by rest
- "keyword query" — regex match against name + description
Returns:
List of matched BaseTool objects (up to MAX_RESULTS).
"""
if query.startswith("select:"):
names = {n.strip() for n in query[7:].split(",")}
return [e.tool for e in self._entries if e.name in names][:MAX_RESULTS]
if query.startswith("+"):
parts = query[1:].split(None, 1)
required = parts[0].lower()
candidates = [e for e in self._entries if required in e.name.lower()]
if len(parts) > 1:
candidates.sort(
key=lambda e: _regex_score(parts[1], e),
reverse=True,
)
return [e.tool for e in candidates][:MAX_RESULTS]
# General regex search
try:
regex = re.compile(query, re.IGNORECASE)
except re.error:
regex = re.compile(re.escape(query), re.IGNORECASE)
scored = []
for entry in self._entries:
searchable = f"{entry.name} {entry.description}"
if regex.search(searchable):
score = 2 if regex.search(entry.name) else 1
scored.append((score, entry))
scored.sort(key=lambda x: x[0], reverse=True)
return [entry.tool for _, entry in scored][:MAX_RESULTS]
@property
def entries(self) -> list[DeferredToolEntry]:
return list(self._entries)
@property
def deferred_names(self) -> set[str]:
"""Names of tools that are still hidden from model binding."""
return {entry.name for entry in self._entries}
def contains(self, name: str) -> bool:
"""Return whether *name* is still deferred."""
return any(entry.name == name for entry in self._entries)
def __len__(self) -> int:
return len(self._entries)
def _regex_score(pattern: str, entry: DeferredToolEntry) -> int:
try:
regex = re.compile(pattern, re.IGNORECASE)
except re.error:
regex = re.compile(re.escape(pattern), re.IGNORECASE)
return len(regex.findall(f"{entry.name} {entry.description}"))
# ── Per-request registry (ContextVar) ──
#
# Using a ContextVar instead of a module-level global prevents concurrent
# requests from clobbering each other's registry. In asyncio-based LangGraph
# each graph run executes in its own async context, so each request gets an
# independent registry value. For synchronous tools run via
# loop.run_in_executor, Python copies the current context to the worker thread,
# so the ContextVar value is correctly inherited there too.
_registry_var: contextvars.ContextVar[DeferredToolRegistry | None] = contextvars.ContextVar("deferred_tool_registry", default=None)
def get_deferred_registry() -> DeferredToolRegistry | None:
return _registry_var.get()
def set_deferred_registry(registry: DeferredToolRegistry) -> None:
_registry_var.set(registry)
def reset_deferred_registry() -> None:
"""Reset the deferred registry for the current async context."""
_registry_var.set(None)
# ── Tool ──
@tool
def tool_search(query: str) -> str:
"""Fetches full schema definitions for deferred tools so they can be called.
Deferred tools appear by name in <available-deferred-tools> in the system
prompt. Until fetched, only the name is known — there is no parameter
schema, so the tool cannot be invoked. This tool takes a query, matches
it against the deferred tool list, and returns the matched tools' complete
definitions. Once a tool's schema appears in that result, it is callable.
Query forms:
- "select:Read,Edit,Grep" — fetch these exact tools by name
- "notebook jupyter" — keyword search, up to max_results best matches
- "+slack send" — require "slack" in the name, rank by remaining terms
Args:
query: Query to find deferred tools. Use "select:<tool_name>" for
direct selection, or keywords to search.
Returns:
Matched tool definitions as JSON array.
"""
registry = get_deferred_registry()
if not registry:
return "No deferred tools available."
matched_tools = registry.search(query)
if not matched_tools:
return f"No tools found matching: {query}"
# Use LangChain's built-in serialization to produce OpenAI function format.
# This is model-agnostic: all LLMs understand this standard schema.
tool_defs = [convert_to_openai_function(t) for t in matched_tools[:MAX_RESULTS]]
# Promote matched tools so the DeferredToolFilterMiddleware stops filtering
# them from bind_tools — the LLM now has the full schema and can invoke them.
registry.promote({t.name for t in matched_tools[:MAX_RESULTS]})
return json.dumps(tool_defs, indent=2, ensure_ascii=False)
@@ -0,0 +1,194 @@
import base64
import mimetypes
from pathlib import Path
from typing import Annotated
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
from langchain_core.messages import ToolMessage
from langgraph.types import Command
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadDataState, ThreadState
from deerflow.config.paths import VIRTUAL_PATH_PREFIX
_ALLOWED_IMAGE_VIRTUAL_ROOTS = (
f"{VIRTUAL_PATH_PREFIX}/workspace",
f"{VIRTUAL_PATH_PREFIX}/uploads",
f"{VIRTUAL_PATH_PREFIX}/outputs",
)
_ALLOWED_IMAGE_VIRTUAL_ROOTS_TEXT = ", ".join(_ALLOWED_IMAGE_VIRTUAL_ROOTS)
_MAX_IMAGE_BYTES = 20 * 1024 * 1024
_EXTENSION_TO_MIME = {
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".png": "image/png",
".webp": "image/webp",
}
def _is_allowed_image_virtual_path(image_path: str) -> bool:
return any(image_path == root or image_path.startswith(f"{root}/") for root in _ALLOWED_IMAGE_VIRTUAL_ROOTS)
def _detect_image_mime(image_data: bytes) -> str | None:
if image_data.startswith(b"\xff\xd8\xff"):
return "image/jpeg"
if image_data.startswith(b"\x89PNG\r\n\x1a\n"):
return "image/png"
if len(image_data) >= 12 and image_data.startswith(b"RIFF") and image_data[8:12] == b"WEBP":
return "image/webp"
return None
def _sanitize_image_error(error: Exception, thread_data: ThreadDataState | None) -> str:
from deerflow.sandbox.tools import mask_local_paths_in_output
return mask_local_paths_in_output(f"{type(error).__name__}: {error}", thread_data)
@tool("view_image", parse_docstring=True)
def view_image_tool(
runtime: ToolRuntime[ContextT, ThreadState],
image_path: str,
tool_call_id: Annotated[str, InjectedToolCallId],
question: str | None = None,
) -> Command:
"""Read and understand an image file.
This is the ONLY correct way to understand an image. The image is analyzed by
the configured vision model and its description/answer is returned to you as
the tool result. Treat that result as authoritative.
When to use the view_image tool:
- Whenever you need to view, describe, or answer a question about an image file.
When NOT to use the view_image tool:
- For non-image files (use present_files instead)
- For multiple files at once (use present_files instead)
IMPORTANT — do NOT attempt to understand images any other way:
- Never read, open, decode, or parse an image with read_file, grep, bash,
python, PIL/Pillow, OpenCV, EXIF parsing, or byte/hex inspection. Those
cannot interpret visual content and will only waste turns.
- If `view_image` returns a weak or incomplete description, do not fall back
to code. Either call `view_image` again with a more specific `question`,
or tell the user the configured vision model could not extract more detail
(the vision model may need to be changed in config).
Args:
image_path: Absolute /mnt/user-data virtual path to the image file. Common formats supported: jpg, jpeg, png, webp.
question: Optional specific question to ask about the image (e.g. "What is the total on this invoice?"). When omitted, a general detailed description is produced.
"""
from deerflow.sandbox.exceptions import SandboxRuntimeError
from deerflow.sandbox.tools import (
get_thread_data,
resolve_and_validate_user_data_path,
validate_local_tool_path,
)
thread_data = get_thread_data(runtime)
if not _is_allowed_image_virtual_path(image_path):
return Command(
update={
"messages": [
ToolMessage(
f"Error: Only image paths under {_ALLOWED_IMAGE_VIRTUAL_ROOTS_TEXT} are allowed",
tool_call_id=tool_call_id,
)
]
},
)
try:
validate_local_tool_path(image_path, thread_data, read_only=True)
actual_path = resolve_and_validate_user_data_path(image_path, thread_data)
except (PermissionError, SandboxRuntimeError) as e:
return Command(
update={"messages": [ToolMessage(f"Error: {str(e)}", tool_call_id=tool_call_id)]},
)
path = Path(actual_path)
# Validate that the file exists
if not path.exists():
return Command(
update={"messages": [ToolMessage(f"Error: Image file not found: {image_path}", tool_call_id=tool_call_id)]},
)
# Validate that it's a file (not a directory)
if not path.is_file():
return Command(
update={"messages": [ToolMessage(f"Error: Path is not a file: {image_path}", tool_call_id=tool_call_id)]},
)
# Validate image extension
expected_mime_type = _EXTENSION_TO_MIME.get(path.suffix.lower())
if expected_mime_type is None:
return Command(
update={"messages": [ToolMessage(f"Error: Unsupported image format: {path.suffix}. Supported formats: {', '.join(_EXTENSION_TO_MIME)}", tool_call_id=tool_call_id)]},
)
# Detect MIME type from file extension
mime_type, _ = mimetypes.guess_type(actual_path)
if mime_type is None:
mime_type = expected_mime_type
try:
image_size = path.stat().st_size
except OSError as e:
return Command(
update={"messages": [ToolMessage(f"Error reading image metadata: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
)
if image_size > _MAX_IMAGE_BYTES:
return Command(
update={"messages": [ToolMessage(f"Error: Image file is too large: {image_size} bytes. Maximum supported size is {_MAX_IMAGE_BYTES} bytes", tool_call_id=tool_call_id)]},
)
# Read image file and convert to base64
try:
with open(actual_path, "rb") as f:
image_data = f.read()
except Exception as e:
return Command(
update={"messages": [ToolMessage(f"Error reading image file: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
)
detected_mime_type = _detect_image_mime(image_data)
if detected_mime_type is None:
return Command(
update={"messages": [ToolMessage("Error: File contents do not match a supported image format", tool_call_id=tool_call_id)]},
)
if detected_mime_type != expected_mime_type:
return Command(
update={"messages": [ToolMessage(f"Error: Image contents are {detected_mime_type}, but file extension indicates {expected_mime_type}", tool_call_id=tool_call_id)]},
)
mime_type = detected_mime_type
image_base64 = base64.b64encode(image_data).decode("utf-8")
# Delegated recognition: when a dedicated vision model is configured, send
# the image to that model and return its description as the tool result, so
# a text-only main chat model can still "see" the image.
from deerflow.models.vision import is_delegated_vision, recognize_image
if is_delegated_vision():
try:
description = recognize_image(image_base64, mime_type, question=question)
except Exception as e: # noqa: BLE001 - surface as a recoverable tool error
return Command(
update={"messages": [ToolMessage(f"Error recognizing image: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
)
if not description:
description = "The vision model returned an empty description."
return Command(
update={"messages": [ToolMessage(f"Image recognition result for {image_path}:\n\n{description}", tool_call_id=tool_call_id)]},
)
# Native vision: store the image so ViewImageMiddleware injects it into the
# (vision-capable) main model before the next LLM call.
# The merge_viewed_images reducer will handle merging with existing images.
new_viewed_images = {image_path: {"base64": image_base64, "mime_type": mime_type}}
return Command(
update={"viewed_images": new_viewed_images, "messages": [ToolMessage("Successfully read image", tool_call_id=tool_call_id)]},
)
@@ -0,0 +1,450 @@
"""Tool for creating and evolving custom skills."""
from __future__ import annotations
import asyncio
import logging
from typing import Any
from weakref import WeakValueDictionary
from langchain.tools import ToolRuntime, tool
from langgraph.typing import ContextT
from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
from deerflow.agents.thread_state import ThreadState
from deerflow.mcp.tools import _make_sync_tool_wrapper
from deerflow.persistence.skills import SkillStore
from deerflow.runtime.user_context import get_effective_user_id
from deerflow.skills.security_scanner import scan_skill_content
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.storage.skill_storage import SkillStorage
from deerflow.skills.types import SKILL_MD_FILE
logger = logging.getLogger(__name__)
_skill_locks: WeakValueDictionary[str, asyncio.Lock] = WeakValueDictionary()
def _get_lock(name: str) -> asyncio.Lock:
lock = _skill_locks.get(name)
if lock is None:
lock = asyncio.Lock()
_skill_locks[name] = lock
return lock
def _get_thread_id(runtime: ToolRuntime[ContextT, ThreadState] | None) -> str | None:
if runtime is None:
return None
if runtime.context and runtime.context.get("thread_id"):
return runtime.context.get("thread_id")
return runtime.config.get("configurable", {}).get("thread_id")
def _history_record(*, action: str, file_path: str, prev_content: str | None, new_content: str | None, thread_id: str | None, scanner: dict[str, Any]) -> dict[str, Any]:
return {
"action": action,
"author": "agent",
"thread_id": thread_id,
"file_path": file_path,
"prev_content": prev_content,
"new_content": new_content,
"scanner": scanner,
}
async def _scan_or_raise(content: str, *, executable: bool, location: str) -> dict[str, str]:
result = await scan_skill_content(content, executable=executable, location=location)
if result.decision == "block":
raise ValueError(f"Security scan blocked the write: {result.reason}")
if executable and result.decision != "allow":
raise ValueError(f"Security scan rejected executable content: {result.reason}")
return {"decision": result.decision, "reason": result.reason}
async def _to_thread(func, /, *args, **kwargs):
return await asyncio.to_thread(func, *args, **kwargs)
async def _bump_patch_best_effort(name: str) -> None:
"""记一次技能维护活动(patch / edit)。
刷新 ``.usage.json`` 的 ``patch_count`` 与 ``last_patched_at``,让 curator 的
年龄流转把"Agent 正在主动维护的技能"算作活跃,而不是误判为闲置后归档。
best-effort:埋点失败只记 DEBUG 日志,绝不影响技能写入主流程。
"""
try:
from deerflow.skills.usage import bump_patch
await _to_thread(bump_patch, name)
except Exception:
logger.debug("Failed to bump patch count for %r", name, exc_info=True)
async def _ensure_skill_db_registered(store: SkillStore, name: str, user_id: str) -> None:
"""Idempotently record an agent-created skill's ownership in the DB.
Mirrors the ``/api/skills/install-upload`` path so agent-created skills
show up in the Web UI listing (which filters custom skills by DB
ownership). ``ensure_legacy`` is idempotent — it never overwrites an
existing owner — so re-running the create flow on an already-owned skill
is a no-op. Failures are swallowed so DB outages can never break the
agent's create flow itself.
"""
try:
await store.ensure_legacy(
{"name": name, "owner_user_id": user_id, "published": False}
)
except Exception:
logger.debug("Failed to register skill ownership for %r", name, exc_info=True)
def _default_skill_store() -> SkillStore | None:
"""Build a ``SkillStore`` backed by the global session factory.
Returns ``None`` if no DB session factory is configured (e.g. ephemeral
test environments), letting the caller skip the registration step
silently.
"""
try:
from deerflow.persistence.engine import get_session_factory
from deerflow.persistence.skills import make_skill_store
factory = get_session_factory()
if factory is None:
return None
return make_skill_store(factory)
except Exception:
logger.debug("Failed to build default skill store", exc_info=True)
return None
def _default_agent_store() -> Any | None:
"""Build an ``AgentStore`` backed by the global session factory."""
try:
from deerflow.persistence.agents import make_agent_store
from deerflow.persistence.engine import get_session_factory
factory = get_session_factory()
if factory is None:
return None
return make_agent_store(factory)
except Exception:
logger.debug("Failed to build default agent store", exc_info=True)
return None
async def _assert_skill_is_agent_authored(name: str) -> None:
"""Refuse to modify skills authored by a human (UI upload / adopt / legacy).
Even when ownership lines up, we draw a hard line at content the *human*
curated through the Web UI: uploads, adopted orphan skills, and legacy
skills with no usage entry (which default to ``source='upload'``).
Those represent reviewed content the user has explicitly endorsed —
letting the agent rewrite them risks silent drift away from what was
approved. Only skills marked ``source='agent'`` (set by
``mark_agent_created`` in the ``create`` flow) remain editable so the
evolution loop can keep refining them.
Raises ``ValueError`` (mapped to a tool error visible to the LLM) on
refusal.
"""
from deerflow.skills.usage import get_entry
entry = await _to_thread(get_entry, name)
if entry.get("source") != "agent":
raise ValueError(
f"Refused: skill '{name}' was authored by a human via the Web UI "
f"and cannot be modified by an agent. Ask the owner to edit it "
f"through the Web UI, or have the user duplicate it to a new "
f"agent-owned skill first."
)
async def _assert_agent_may_modify(store: SkillStore, name: str, user_id: str) -> dict[str, Any]:
"""Pre-flight ownership check before an agent-driven write touches a custom skill.
LocalSkillStorage operates by name only — patch/edit/write_file/remove_file
and delete all resolve a name to a directory without knowing who owns it.
Without this guard a malicious or hallucinating agent could overwrite or
destroy another user's skill (including UI-uploaded skills) just by
knowing the name. We refuse unless the DB confirms ``user_id`` owns the
skill outright.
Returns the DB record so callers that need owner info (e.g. delete
cascade) can reuse it. Raises ``ValueError`` (mapped to a tool error
visible to the LLM) on refusal.
"""
record = await store.get_any(name)
if record is None:
# No DB row — could be a legacy/orphan skill. Refuse rather than
# touch blindly; users should adopt it via /api/skills/reconcile-custom
# or an admin can clean it up via the Web UI.
raise ValueError(
f"Refused: skill '{name}' has no ownership record. Ask a human to adopt or manage it via the Web UI."
)
owner = record.get("owner_user_id")
if owner is None:
raise ValueError(f"Refused: skill '{name}' is built-in and cannot be modified by an agent.")
if owner != user_id:
raise ValueError(f"Refused: skill '{name}' is owned by another user.")
return record
async def _skill_manage_impl(
runtime: ToolRuntime[ContextT, ThreadState],
action: str,
name: str,
content: str | None = None,
path: str | None = None,
find: str | None = None,
replace: str | None = None,
expected_count: int | None = None,
) -> str:
"""Manage custom skills under skills/custom/.
Args:
action: One of create, patch, edit, delete, write_file, remove_file.
For listing or viewing skills, prefer the dedicated
``skill_list`` / ``skill_view`` tools — but ``action='list'``
and ``action='view'`` are accepted here as convenience
aliases that delegate to those tools.
name: Skill name in hyphen-case.
content: New file content for create, edit, or write_file.
path: Supporting file path for write_file or remove_file.
find: Existing text to replace for patch.
replace: Replacement text for patch.
expected_count: Optional expected number of replacements for patch.
"""
# Read-only aliases — delegate to the dedicated tools so a model that
# over-uses skill_manage doesn't trip on Unsupported action errors.
# Pass the active agent_id through so a custom agent's skill whitelist
# is enforced on these aliases just like on skill_list/skill_view.
if action == "list":
from deerflow.tools.builtins.skill_tools import _resolve_active_agent_id, skill_list_impl
return await _to_thread(skill_list_impl, _resolve_active_agent_id(runtime))
if action == "view":
from deerflow.tools.builtins.skill_tools import _resolve_active_agent_id, skill_view_impl
return await _to_thread(skill_view_impl, name, _resolve_active_agent_id(runtime))
name = SkillStorage.validate_skill_name(name)
lock = _get_lock(name)
thread_id = _get_thread_id(runtime)
skill_storage = get_or_new_skill_storage()
# Resolved up-front so ownership checks in the write-action branches stay
# one-liners. Cheap when the DB is unconfigured (returns None).
user_id = get_effective_user_id()
skill_store = _default_skill_store()
async with lock:
if action == "create":
if await _to_thread(skill_storage.custom_skill_exists, name):
raise ValueError(f"Custom skill '{name}' already exists.")
if content is None:
raise ValueError("content is required for create.")
await _to_thread(skill_storage.validate_skill_markdown_content, name, content)
scan = await _scan_or_raise(content, executable=False, location=f"{name}/{SKILL_MD_FILE}")
await _to_thread(skill_storage.write_custom_skill, name, SKILL_MD_FILE, content)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="create", file_path=SKILL_MD_FILE, prev_content=None, new_content=content, thread_id=thread_id, scanner=scan),
)
try:
from deerflow.skills.usage import mark_agent_created
await _to_thread(mark_agent_created, name)
except Exception:
pass
# Register the new skill in the DB so the web UI listing actually
# surfaces it (custom skills without a DB row are filtered out by
# ``GET /api/skills``). Resolve the user_id *here* on the main
# async stack — contextvars don't propagate into ``to_thread``.
if skill_store is not None:
await _ensure_skill_db_registered(skill_store, name, user_id)
await refresh_skills_system_prompt_cache_async()
return f"Created custom skill '{name}'."
if action == "edit":
await _to_thread(skill_storage.ensure_custom_skill_is_editable, name)
if skill_store is not None:
await _assert_agent_may_modify(skill_store, name, user_id)
await _assert_skill_is_agent_authored(name)
if content is None:
raise ValueError("content is required for edit.")
await _to_thread(skill_storage.validate_skill_markdown_content, name, content)
scan = await _scan_or_raise(content, executable=False, location=f"{name}/{SKILL_MD_FILE}")
skill_file = skill_storage.get_custom_skill_file(name)
prev_content = await _to_thread(skill_file.read_text, encoding="utf-8")
await _to_thread(skill_storage.write_custom_skill, name, SKILL_MD_FILE, content)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="edit", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Updated custom skill '{name}'."
if action == "patch":
await _to_thread(skill_storage.ensure_custom_skill_is_editable, name)
if skill_store is not None:
await _assert_agent_may_modify(skill_store, name, user_id)
await _assert_skill_is_agent_authored(name)
if find is None or replace is None:
raise ValueError("find and replace are required for patch.")
skill_file = skill_storage.get_custom_skill_file(name)
prev_content = await _to_thread(skill_file.read_text, encoding="utf-8")
occurrences = prev_content.count(find)
if occurrences == 0:
raise ValueError("Patch target not found in SKILL.md.")
if expected_count is not None and occurrences != expected_count:
raise ValueError(f"Expected {expected_count} replacements but found {occurrences}.")
replacement_count = expected_count if expected_count is not None else 1
new_content = prev_content.replace(find, replace, replacement_count)
await _to_thread(skill_storage.validate_skill_markdown_content, name, new_content)
scan = await _scan_or_raise(new_content, executable=False, location=f"{name}/{SKILL_MD_FILE}")
await _to_thread(skill_storage.write_custom_skill, name, SKILL_MD_FILE, new_content)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="patch", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=new_content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Patched custom skill '{name}' ({replacement_count} replacement(s) applied, {occurrences} match(es) found)."
if action == "delete":
# Ownership pre-check: LocalSkillStorage deletes purely by name,
# so without this an agent could blow away another user's skill
# just by knowing the name. Raise BEFORE touching the filesystem.
record: dict[str, Any] | None = None
if skill_store is not None:
record = await _assert_agent_may_modify(skill_store, name, user_id)
await _assert_skill_is_agent_authored(name)
await _to_thread(
skill_storage.delete_custom_skill,
name,
history_meta=_history_record(
action="delete",
file_path=SKILL_MD_FILE,
prev_content=None,
new_content=None,
thread_id=thread_id,
scanner={"decision": "allow", "reason": "Deletion requested."},
),
)
# Mirror what ``DELETE /api/skills/custom/{name}`` does: drop the
# ``.usage.json`` entry and the DB ownership row, then cascade
# the removal to every agent that referenced this skill so
# ``config.yaml`` doesn't end up with a dangling reference.
# Failures are best-effort — the on-disk delete already happened
# and is authoritative.
try:
from deerflow.skills.usage import forget
await _to_thread(forget, name)
except Exception:
logger.debug("Failed to forget usage entry for %r", name, exc_info=True)
if skill_store is not None:
try:
await skill_store.delete(name, user_id)
except Exception:
logger.debug("Failed to delete DB row for %r", name, exc_info=True)
agent_store = _default_agent_store()
if agent_store is not None:
try:
from deerflow.skills.cascade import cascade_skill_unpublished_or_deleted
await cascade_skill_unpublished_or_deleted(
name,
actor_user_id=user_id,
operation="delete",
skill_owner_user_id=(record.get("owner_user_id") if record else user_id),
agent_store=agent_store,
)
except Exception:
logger.debug("Cascade failed for deleted skill %r", name, exc_info=True)
await refresh_skills_system_prompt_cache_async()
return f"Deleted custom skill '{name}'."
if action == "write_file":
await _to_thread(skill_storage.ensure_custom_skill_is_editable, name)
if skill_store is not None:
await _assert_agent_may_modify(skill_store, name, user_id)
await _assert_skill_is_agent_authored(name)
if path is None or content is None:
raise ValueError("path and content are required for write_file.")
target = await _to_thread(skill_storage.ensure_safe_support_path, name, path)
exists = await _to_thread(target.exists)
prev_content = await _to_thread(target.read_text, encoding="utf-8") if exists else None
executable = "scripts/" in path or path.startswith("scripts/")
scan = await _scan_or_raise(content, executable=executable, location=f"{name}/{path}")
await _to_thread(skill_storage.write_custom_skill, name, path, content)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="write_file", file_path=path, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
return f"Wrote '{path}' for custom skill '{name}'."
if action == "remove_file":
await _to_thread(skill_storage.ensure_custom_skill_is_editable, name)
if skill_store is not None:
await _assert_agent_may_modify(skill_store, name, user_id)
await _assert_skill_is_agent_authored(name)
if path is None:
raise ValueError("path is required for remove_file.")
target = await _to_thread(skill_storage.ensure_safe_support_path, name, path)
if not await _to_thread(target.exists):
raise FileNotFoundError(f"Supporting file '{path}' not found for skill '{name}'.")
prev_content = await _to_thread(target.read_text, encoding="utf-8")
await _to_thread(target.unlink)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="remove_file", file_path=path, prev_content=prev_content, new_content=None, thread_id=thread_id, scanner={"decision": "allow", "reason": "Deletion requested."}),
)
return f"Removed '{path}' from custom skill '{name}'."
if await _to_thread(skill_storage.public_skill_exists, name):
raise ValueError(f"'{name}' is a built-in skill. To customise it, create a new skill with the same name under skills/custom/.")
raise ValueError(f"Unsupported action '{action}'.")
@tool("skill_manage", parse_docstring=True)
async def skill_manage_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: str,
name: str,
content: str | None = None,
path: str | None = None,
find: str | None = None,
replace: str | None = None,
expected_count: int | None = None,
) -> str:
"""Manage custom skills under skills/custom/.
Args:
action: One of create, patch, edit, delete, write_file, remove_file.
name: Skill name in hyphen-case.
content: New file content for create, edit, or write_file.
path: Supporting file path for write_file or remove_file.
find: Existing text to replace for patch.
replace: Replacement text for patch.
expected_count: Optional expected number of replacements for patch.
"""
return await _skill_manage_impl(
runtime=runtime,
action=action,
name=name,
content=content,
path=path,
find=find,
replace=replace,
expected_count=expected_count,
)
skill_manage_tool.func = _make_sync_tool_wrapper(_skill_manage_impl, "skill_manage")
@@ -0,0 +1,314 @@
import logging
from langchain.tools import BaseTool
from deerflow.config import get_app_config
from deerflow.config.app_config import AppConfig
from deerflow.reflection import resolve_variable
from deerflow.sandbox.security import is_host_bash_allowed
from deerflow.tools.builtins import agent_orchestration_tool, ask_clarification_tool, memory_tool, present_file_tool, scheduled_task_tool, task_tool, view_image_tool
from deerflow.tools.builtins.tool_search import reset_deferred_registry
logger = logging.getLogger(__name__)
BROWSER_CONTEXT_TOOL_USE = "deerflow.tools.builtins.browser_context_tool:browser_fetch_page_tool"
BROWSER_ACT_TOOL_USE = "deerflow.tools.builtins.browser_act_tool:browser_act_tool"
BROWSER_CONTEXT_TOOL_USES = {BROWSER_CONTEXT_TOOL_USE, BROWSER_ACT_TOOL_USE}
BROWSER_CONTEXT_TOOL_NAMES = {"browser_fetch_page", "browser_act"}
BUILTIN_TOOLS = [
present_file_tool,
ask_clarification_tool,
]
SUBAGENT_TOOLS = [
task_tool,
# task_status_tool is no longer exposed to LLM (backend handles polling internally)
]
def _is_host_bash_tool(tool: object) -> bool:
"""Return True if the tool config represents a host-bash execution surface."""
group = getattr(tool, "group", None)
use = getattr(tool, "use", None)
if group == "bash":
return True
if use == "deerflow.sandbox.tools:bash_tool":
return True
return False
def _is_browser_context_tool(tool: object) -> bool:
"""Return True if the tool config represents the browser extension bridge."""
use = getattr(tool, "use", None)
name = getattr(tool, "name", None)
return use in BROWSER_CONTEXT_TOOL_USES or name in BROWSER_CONTEXT_TOOL_NAMES
def _enforce_agent_orchestration_scope(
tools: list[BaseTool],
*,
allow_agent_orchestration: bool,
) -> list[BaseTool]:
"""Fail closed: only an explicitly authorized coordinator may receive orchestration."""
if allow_agent_orchestration:
return tools
return [tool for tool in tools if tool.name != "agent_orchestration"]
def get_available_tools(
groups: list[str] | None = None,
include_mcp: bool = True,
model_name: str | None = None,
subagent_enabled: bool = False,
is_scheduled_run: bool = False,
excluded_tools: list[str] | None = None,
*,
allow_agent_orchestration: bool = False,
app_config: AppConfig | None = None,
) -> list[BaseTool]:
"""Get all available tools from config.
Note: MCP tools should be initialized at application startup using
`initialize_mcp_tools()` from deerflow.mcp module.
Args:
groups: Optional list of tool groups to filter by.
include_mcp: Whether to include tools from MCP servers (default: True).
model_name: Optional model name to determine if vision tools should be included.
subagent_enabled: Whether to include subagent tools (task, task_status).
excluded_tools: Optional list of tool names to exclude from the result
(applied AFTER all other resolution). Takes precedence over
``app_config.excluded_tools``.
allow_agent_orchestration: Explicit coordinator-only capability gate. Defaults to
``False`` so ordinary agents and all indirect callers fail closed.
Returns:
List of available tools.
"""
config = app_config or get_app_config()
selected_tool_configs = [tool for tool in config.tools if groups is None or tool.group in groups]
disabled_tool_names = [tool.name for tool in selected_tool_configs if not tool.enabled]
if disabled_tool_names:
logger.info("Skipping disabled configured tool(s): %s", disabled_tool_names)
tool_configs = [tool for tool in selected_tool_configs if tool.enabled]
browser_context_config = getattr(config, "browser_context", None)
if not getattr(browser_context_config, "enabled", False):
tool_configs = [tool for tool in tool_configs if not _is_browser_context_tool(tool)]
elif not getattr(browser_context_config, "actions_enabled", True):
# browser_context is on, but interactive page actions are disabled — keep
# the read-only browser_fetch_page tool, drop only browser_act.
tool_configs = [
tool
for tool in tool_configs
if getattr(tool, "use", None) != BROWSER_ACT_TOOL_USE and getattr(tool, "name", None) != "browser_act"
]
# Do not expose host bash by default when LocalSandboxProvider is active.
if not is_host_bash_allowed(config):
tool_configs = [tool for tool in tool_configs if not _is_host_bash_tool(tool)]
loaded_tools_raw = [(cfg, resolve_variable(cfg.use, BaseTool)) for cfg in tool_configs]
# Warn when the config ``name`` field and the tool object's ``.name``
# attribute diverge — this mismatch is the root cause of issue #1803 where
# the LLM receives one name in its tool schema but the runtime router
# recognises a different name, producing "not a valid tool" errors.
for cfg, loaded in loaded_tools_raw:
if cfg.name != loaded.name:
logger.warning(
"Tool name mismatch: config name %r does not match tool .name %r (use: %s). The tool's own .name will be used for binding.",
cfg.name,
loaded.name,
cfg.use,
)
loaded_tools = [t for _, t in loaded_tools_raw]
# Conditionally add tools based on config
builtin_tools = BUILTIN_TOOLS.copy()
if allow_agent_orchestration:
builtin_tools.append(agent_orchestration_tool)
if not is_scheduled_run:
builtin_tools.append(scheduled_task_tool)
# Memory V2:记忆与 builtin provider 都启用时,暴露 memory 工具给 LLM 主动写入
memory_config = getattr(config, "memory", None)
if memory_config is not None and getattr(memory_config, "enabled", False):
builtin_config = getattr(memory_config, "builtin", None)
if builtin_config is not None and getattr(builtin_config, "enabled", False):
builtin_tools.append(memory_tool)
logger.info("Including memory tool (Memory V2 builtin provider enabled)")
# Hindsight 在 tools / hybrid 模式下,额外暴露 3 个 Hindsight 工具
if getattr(memory_config, "provider", "builtin") == "hindsight":
hindsight_config = getattr(memory_config, "hindsight", None)
memory_mode = getattr(hindsight_config, "memory_mode", "context") if hindsight_config else "context"
if memory_mode in ("tools", "hybrid"):
from deerflow.tools.builtins.hindsight_tools import HINDSIGHT_TOOLS
builtin_tools.extend(HINDSIGHT_TOOLS)
logger.info("Including Hindsight tools (memory_mode=%s)", memory_mode)
skill_evolution_config = getattr(config, "skill_evolution", None)
# skill_list / skill_view 是只读工具(发现、查看技能),与"自我进化"写能力无关,
# 始终提供给 agent。
from deerflow.tools.builtins.skill_tools import skill_list_tool, skill_view_tool
builtin_tools.extend([skill_list_tool, skill_view_tool])
# search_skills —— 仅当管理员开启"技能压缩"时提供。压缩开启后,非常驻技能不再
# 全文注入系统提示词,agent 通过该关键词检索工具按需调出(纯关键词、离线、确定性)。
try:
from deerflow.config.system_settings import get_skill_compression_settings
if get_skill_compression_settings().enabled:
from deerflow.tools.builtins.skill_tools import search_skills_tool
builtin_tools.append(search_skills_tool)
except Exception: # noqa: BLE001 - 读取设置失败不能阻断 agent 构建
logger.debug("Failed to evaluate skill compression setting for search_skills tool", exc_info=True)
# read_peer_delivery —— 圆桌席位「按需读取前序席位完整交付」的只读工具(从 run context
# 取网关注入的全文,非圆桌场景为空 → 工具自述「无」)。始终提供(只读、无副作用);圆桌
# 总控/报告角色由 run policy 显式排除,避免干扰它们。
from deerflow.tools.builtins.roundtable_peers_tool import read_peer_delivery_tool
builtin_tools.append(read_peer_delivery_tool)
# Conditional LLMWiki mode: the tool is absent when no effective WeKnora
# address is configured, keeping legacy deployments behavior-identical.
try:
from deerflow.integrations.weknora.runtime import get_resolved_llmwiki_runtime
if get_resolved_llmwiki_runtime(config).weknora_enabled:
from deerflow.tools.builtins.llmwiki_search_tool import llmwiki_search_tool
builtin_tools.append(llmwiki_search_tool)
except Exception: # noqa: BLE001 - configuration/store failures must not block agent creation
logger.debug("Failed to evaluate the conditional LLMWiki search tool", exc_info=True)
# skill_manage 能创建/修改/删除技能,属于"自我进化"写能力,按 skill_evolution.enabled
# 门控。该开关用户可在 per-user 配置里覆盖,所以按"生效配置(含 per-user 覆盖)"判断 ——
# Gateway 每次 run 重建 agent,用户改了配置下次 run 即生效;解析失败退回全局 config.yaml。
try:
from deerflow.config.skill_evolution_runtime import load_skill_evolution_config_for_user
from deerflow.runtime.user_context import get_effective_user_id
skill_evolution_config = load_skill_evolution_config_for_user(get_effective_user_id())
except Exception: # noqa: BLE001 - 解析失败不能阻断 agent 构建
skill_evolution_config = getattr(config, "skill_evolution", None)
if getattr(skill_evolution_config, "enabled", False):
from deerflow.tools.skill_manage_tool import skill_manage_tool
builtin_tools.append(skill_manage_tool)
# Add subagent tools only if enabled via runtime parameter
if subagent_enabled:
builtin_tools.extend(SUBAGENT_TOOLS)
logger.info("Including subagent tools (task)")
# If no model_name specified, use the first model (default)
if model_name is None and config.models:
model_name = config.models[0].name
# Add view_image_tool when vision is available — either the main model
# supports vision natively, or a dedicated vision model is configured
# (vision.model_name) so recognition can be delegated to it.
from deerflow.models.vision import vision_enabled
if vision_enabled(model_name, app_config=config):
builtin_tools.append(view_image_tool)
logger.info(f"Including view_image_tool for model '{model_name}' (vision available)")
# Get cached MCP tools if enabled
# NOTE: We use ExtensionsConfig.from_file() instead of config.extensions
# to always read the latest configuration from disk. This ensures that changes
# made through the Gateway API (which runs in a separate process) are immediately
# reflected when loading MCP tools.
mcp_tools = []
# Reset deferred registry upfront to prevent stale state from previous calls
reset_deferred_registry()
if include_mcp:
try:
from deerflow.config.extensions_config import ExtensionsConfig
from deerflow.mcp.cache import get_cached_mcp_tools
extensions_config = ExtensionsConfig.from_file()
if extensions_config.get_enabled_mcp_servers():
mcp_tools = get_cached_mcp_tools()
if mcp_tools:
logger.info(f"Using {len(mcp_tools)} cached MCP tool(s)")
# When tool_search is enabled, register MCP tools in the
# deferred registry and add tool_search to builtin tools.
if config.tool_search.enabled:
from deerflow.tools.builtins.tool_search import DeferredToolRegistry, set_deferred_registry
from deerflow.tools.builtins.tool_search import tool_search as tool_search_tool
registry = DeferredToolRegistry()
for t in mcp_tools:
registry.register(t)
set_deferred_registry(registry)
builtin_tools.append(tool_search_tool)
logger.info(f"Tool search active: {len(mcp_tools)} tools deferred")
except ImportError:
logger.warning("MCP module not available. Install 'langchain-mcp-adapters' package to enable MCP tools.")
except Exception as e:
logger.error(f"Failed to get cached MCP tools: {e}")
# Add invoke_acp_agent tool if any ACP agents are configured
acp_tools: list[BaseTool] = []
try:
from deerflow.tools.builtins.invoke_acp_agent_tool import build_invoke_acp_agent_tool
if app_config is None:
from deerflow.config.acp_config import get_acp_agents
acp_agents = get_acp_agents()
else:
acp_agents = getattr(config, "acp_agents", {}) or {}
if acp_agents:
acp_tools.append(build_invoke_acp_agent_tool(acp_agents))
logger.info(f"Including invoke_acp_agent tool ({len(acp_agents)} agent(s): {list(acp_agents.keys())})")
except Exception as e:
logger.warning(f"Failed to load ACP tool: {e}")
logger.info(f"Total tools loaded: {len(loaded_tools)}, built-in tools: {len(builtin_tools)}, MCP tools: {len(mcp_tools)}, ACP tools: {len(acp_tools)}")
# Deduplicate by tool name — config-loaded tools take priority, followed by
# built-ins, MCP tools, and ACP tools. Duplicate names cause the LLM to
# receive ambiguous or concatenated function schemas (issue #1803).
all_tools = loaded_tools + builtin_tools + mcp_tools + acp_tools
seen_names: set[str] = set()
unique_tools: list[BaseTool] = []
for t in all_tools:
if t.name not in seen_names:
unique_tools.append(t)
seen_names.add(t.name)
else:
logger.warning(
"Duplicate tool name %r detected and skipped — check your config.yaml and MCP server registrations (issue #1803).",
t.name,
)
# Drop tools the caller (or config) wants excluded. Request-level
# ``excluded_tools`` wins; the config-level list is the static fallback.
effective_excluded = excluded_tools if excluded_tools else getattr(config, "excluded_tools", None) or []
if effective_excluded:
excluded_set = set(effective_excluded)
filtered_tools = [t for t in unique_tools if t.name not in excluded_set]
if len(filtered_tools) < len(unique_tools):
logger.info(
"Excluded %d tool(s) by request/config: %s",
len(unique_tools) - len(filtered_tools),
effective_excluded,
)
unique_tools = filtered_tools
# Defense in depth: a config/MCP tool with the reserved name must not bypass the builtin gate.
return _enforce_agent_orchestration_scope(
unique_tools,
allow_agent_orchestration=allow_agent_orchestration,
)