配置与二次开发

如何调整智能体参数，以及如何手把手添加一个新工具

1. 配置与调优参数

Configuration

智能体的核心行为（如思考深度、检索广度）可以通过 Flask 的 config.py 或环境变量进行热调整，无需修改代码。

参数名 (Key)	默认值	说明与用途
AGENT_MAX_STEPS	`3`	最大规划步数。决定了 Agent 在回答前能进行多少次“思考-工具调用”循环。增加该值可处理更复杂任务，但会增加延迟。
AGENT_LLM_MAX_ITEMS	`5`	单步上下文容量。每个工具调用后，截取前 N 条结果送入 LLM。降低该值可节省 Token，但可能丢失细节；提高则反之。
DEEPSEEK_API_KEY	Required	DeepSeek V3 模型的 API 密钥，用于 Planner 和 Responder。
DASHSCOPE_RERANK_MODEL	`gte-rerank-v2`	阿里云千问重排模型名称。可选 `gte-rerank` (v1) 或其他兼容模型。
METASO_API_KEY	Optional	用于 `web_search` 和 `web_read` 的联网搜索能力密钥。

💡 调优建议当你发现智能体经常“浅尝辄止”回答不完整时，尝试将 AGENT_MAX_STEPS 调至 5；如果发现回答时容易忽略后半部分的搜索结果，尝试降低 AGENT_LLM_MAX_ITEMS 以减少上下文噪音。

2. 扩展：新增一个工具

本系统设计了插拔式的工具架构。假设你需要接入“图书馆藏书查询”功能，只需两步即可完成扩展。

1️⃣

Step 1: 实现工具函数

在 tools/ 目录下新建或修改文件，编写 Python 函数。
约定：必须返回包含 ok (bool) 和 items (list) 或 markdown (str) 的字典。

PYTHON

# tools/library_tools.py

from typing import Dict, Any, Optional

def search_library(text: str, size: int = 5, question: Optional[str] = None) -> Dict[str, Any]:
    """
    检索图书馆藏书信息。
    :param text: 书名关键词
    """
    # 1. 模拟调用外部 API
    api_results = _call_library_api(text, limit=size)

    # 2. 构造返回结构
    return {
        "ok": True,
        "items": api_results,    # 结构化数据，供 Agent 思考
        "source": [...]          # 可选，用于前端生成引用链接
    }

2️⃣

Step 2: 注册到智能体

为了让 LLM 知道这个工具的存在，并让后端能够正确分发调用，需要在 agent.py 中完成注册。

注册清单 Checklist

1
声明工具定义：
在 allowed_tools 字典中添加工具名及参数约束（Schema）。这决定了 LLM 能看到什么工具。
2
添加分发逻辑：
在 dispatch_tool 函数中增加 elif tool == "search_library": 分支，对接刚才写的函数。
3
配置结果摘要：
在 _summ_step_for_llm 中添加逻辑，告诉 LLM 该如何阅读这个工具返回的 JSON 数据（如只看前 3 本书的标题）。

agent.py (Snippet)

# 1. 允许 LLM 调用
allowed_tools = {
    # ... 其他工具
    "search_library": {
        "text": "书名关键词",
        "size": "返回数量，默认5"
    }
}

# 2. 分发调用
if tool == "search_library":
    result = search_library(
        text=args.get("text"),
        size=min(args.get("size", 5), 10)
    )

🎉 完成！完成以上两步后，无需重启复杂服务，Agent 即可在下一次规划中自动识别并使用 search_library 工具来回答相关问题。