创建一个有根基的支持智能体

在构建之前——先探索，不要盲目运行。 向租户了解他们的工作、材料、运行的流程以及需要交互的系统；规划整体设置（根据需要配置智能体、知识库、技能和 MCP），并在创建任何内容之前进行演练。以下步骤是在此之后运行的——请参阅构建前的探索。

原则——一个智能体，一项工作。 为该智能体分配单一且明确定义的任务。如果业务有三项工作（支持、销售和调度），请构建三个智能体——“什么都能做”的智能体会把每件事都做得更差。更多信息请参阅设计原则。

智能体由 soul + task + tools + skills + knowledge_bases 组成。soul 是身份和语气；task 是工作及其边界——两者都放入系统提示词的固定前缀中。

1. 查看可附加的内容

list_tools()             # tools available to this tenant (including connected MCP tools)
list_knowledge_bases()   # knowledge bases you can mount

2. 创建它

默认开启，因此你无需专门请求。 新智能体在需要两个或三个事实才能回答之前，已经可以使用可点击的单选/多选表单（ask_forms）进行回复，并且已经可以绘制图表（compute_chart 在默认工具列表中）。在 2026-08-03 之前，这两项功能默认是关闭的，且创建调用没有针对第一项的参数——因此在此之前构建的智能体两者都没有，而 update_agent(ask_forms=True, add_tools=["compute_chart"]) 是将其更新到最新状态的方法。

传递 tools=[...] 会替换默认列表，而不是添加到其中，因此只要传递了工具，就必须自行包含 compute_chart。

名称为小写。 名称不仅是你看到的内容——有十一个表通过名称引用智能体（共享、会话、故事线、渠道绑定、使用情况），因此 Pip 和 pip 对它们来说是两个不同的智能体，而对你来说是同一个。新名称在保存时会被转换为小写；以这种方式编写它们，无需进行任何协调。它也不是公共 URL——那是 alias。

create_agent(
  name="support",                  # lower-case; the platform lower-cases it anyway
  alias="support",                 # public human-readable URL slug — set one (url-safe, lowercase)
  soul="You are the support assistant for Acme Loans. Professional and warm.",
  task="Answer questions about mortgage products and the application process. "
       "Never promise a disbursement date; never give legal or tax advice; "
       "for any specific quote, call a tool — do not answer from memory.",
  tools=["web_search"],
  knowledge_bases=["company-policy"],   # use the KB's returned slug name (see below)
  published=True,
)

• alias 是智能体的公共人类可读地址段（{public_base}/t/<tenant>/<alias>）——设置它以便你可以给人们一个令人难忘的链接。它会被规范化为 URL 安全的段；如果发生冲突，会在 alias_result 中返回。
• 系统工具默认开启。 新智能体自动获得 current_time、ip_geo 和 weather（内置的 system MCP）——你不需要列出它们；tools 用于额外的工具。
• URL 中的名称会被段化。 知识库名称在创建时会变为 URL 安全的段（"Company Policy" → company-policy）；通过返回的名称附加它，而不是你输入的名称。

3. 确认已落地

get_agent(name="Support")   # writing it doesn't mean it looks the way you intended

边界属于 task——负面约束（“从不承诺……”）比正面描述更能防止漂移。不要将安全规则放在 soul 中；平台会自动附加全局审核。要稍后更改一个字段，请使用 update_agent(name, field=…)——它会合并，因此不会清空其余部分。

4. 发布它——询问如何，然后使其可访问

在说“完成”之前，询问租户他们的客户应如何访问它，然后使用 create_share 连接该渠道（它返回一个真实、可打开的链接——将该链接交回，而不是“已发布”）：

create_share(agent_name="Support", label="Website widget")
# → { token, chat_url, qr_url, embed_snippet, pretty_url, … }

如果响应包含 pretty_url（…/t/<tenant-alias>/<agent-alias>），这就是人类的链接——可读且在令牌轮换期间保持稳定。如果它为 null，请设置缺失的别名（create_agent(alias=…) / PUT /agents/{name}/alias；控制台中的租户别名 → 设置），而不是发送令牌链接。chat_url 仍然适用于嵌入和二维码。

• 没有网站——只有链接或二维码（自由职业者、商店、传单、名片）：交回 chat_url（全屏托管聊天页面——无需网站）和 qr_url（可打印的二维码）。它是匿名的：无需登录，每个访问者都通过其浏览器被记住，因此常客会被识别。
• 他们自己的网站：提供 embed_snippet（</body> 之前的一行代码用于浮动小部件），或 chat_url 用于链接/iframe。
• Telegram / WhatsApp：在控制台中按渠道设置（智能体 → 集成 → Telegram / WhatsApp）；指引他们前往那里。

回报。 交回他们现在可以打开和测试的实际链接（chat_url，以及他们没有网站时的 qr_url），以及审查它的控制台页面—— https://console.agent4.io/#/agents/Support。不是“已发布”——而是链接。