集成模式

两种接入方式

大多数团队一开始会选择命令式写法，因为它看起来更简单：

# Imperative: your code decides, always, on every turn.
context = hive.search(user_question)        # always fires, relevant or not
answer  = llm(prompt=user_question, context=context)
return answer

而工具调用方式则把这一判断交给模型：

# Tool-based: the model decides whether to search, what to search for,
# and whether what came back was worth a follow-up query.
tools = [
    {
        "name": "search_team_knowledge",
        "description": (
            "Search the team's knowledge base for prior decisions, standards "
            "and meeting outcomes. Use whenever the answer might depend on "
            "something the team already decided. Prefer this over guessing."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "question": {
                    "type": "string",
                    "description": "A natural-language question, not keywords.",
                }
            },
            "required": ["question"],
        },
    },
]
# ... on a tool_use block, call aiqbee_search and return the result.

为什么第二种更好

1. 检索质量取决于查询，而模型更擅长写查询

aiqbee_search是语义搜索。直接传入用户的原话，效果尚可；传入一个表述清晰的问题，效果会好得多。模型能看到完整对话，因此可以把“我们是不是否决了那个方案？”转换为“公共API限流最终是怎么决定的？”而您的代码做不到，因为它不知道“那个”指的是什么。

2. 大多数对话轮次根本不需要搜索

像“谢谢，搞定了”这样的话根本无需检索。无条件搜索既增加延迟，又会把无关上下文塞进提示词，明显拉低回答质量。让模型自行决定不搜索是一项特性，而不是偷懒。

3. 一次搜索往往不够

实际问题往往需要先搜索一次，查看返回结果，再进行一次范围更小的搜索。这种循环天然适合工具调用，却很难用固定的控制流来表达。

4. 回写才是记忆层真正发挥价值的地方

这是大多数集成都会省略的一步，却恰恰是关键所在。同时为模型提供写入工具，知识就会在日常工作中自然积累，而无需有人记着去整理归档。

{
    "name": "record_team_knowledge",
    "description": (
        "Record a durable decision, standard or outcome so it is available "
        "to the team later. Use when something is settled that a colleague "
        "would need in six months. Do NOT use for chit-chat, transient "
        "status, or anything you were not told."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "title":   {"type": "string"},
            "content": {"type": "string",
                        "description": "Include who, what and WHY. Self-contained."},
            "type_id": {"type": "string",
                        "description": "A real id from aiqbee_get_neuron_types."},
        },
        "required": ["title", "content", "type_id"],
    },
}

编写有效的工具描述

描述才是真正的集成界面：它就是决定工具能否被正确使用的提示词。以下几点始终很关键：

• 说明何时使用，而不仅是它能做什么。“搜索知识库”会导致调用时有时无。“当答案可能取决于团队之前的决定时使用”则能让模型恰当地调用。
• 说明不该调用的情况。如果没有明确的排除说明，写入工具会在寒暄时被调用，Brain里就会充满噪声。
• 说明理想输入的形式。“使用自然语言提问，而不是关键词”这样一句话就能改变模型发送的内容。
• 原样返回错误。Hive的错误信息都写得便于采取行动：例如重复内容被拒绝时，会返回已有的神经元，以便模型改为更新或建立链接。如果吞掉这些错误，就失去了自我纠正的机会。

建议在代码中保留的防护措施

让模型判断何时调用，并不等于赋予它不受限制的权限。以下控制应保留在您这一侧：

• 最小权限原则。除非智能体确实需要写入，否则只为服务账号授予只读访问权限。访问权限按Brain分别授予。
• 每个集成使用独立身份。每个智能体对应一个服务账号，这样审计历史和撤销操作才有意义。
• 对破坏性调用进行确认。删除类工具最好完全不纳入工具集，或要求人工审批后才能执行。
• 对任何受监管的场景都应开启审计：这样每次写入都能追溯到发起调用的服务账号。此为付费功能；请参阅许可证&版本。

何时适合直接调用

直接调用也有其合理场景：确定性的、非对话式的工作，例如批量导入文档、每晚同步、配置脚本、数据迁移。这类工作无需判断，也就无需交给模型，直接使用REST API或调用MCP工具即可，保持简单。