建立穩健的支援代理

在構建之前——先探索，不要盲目執行。 向租戶訪談其工作內容、使用的材料、執行的程序以及必須連接的系統；規劃整體設置（代理程式 + 知識庫 + 技能 + 按需的 MCP），並在創建任何內容之前進行模擬演練。以下步驟是在完成上述工作後執行的——請參閱 構建前的探索。

原則——一個代理程式，一項工作。 賦予此代理程式單一且邊界清晰的任務。如果企業有三項工作（客服 和 銷售 和 排程），請建立三個代理程式——「什麼都做」的代理程式對每項工作的處理效果都會更差。更多內容請參閱 設計原則。

代理程式由 靈魂 + 任務 + 工具 + 技能 + 知識庫 組成。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 安全的 slug；如果發生衝突，會在 alias_result 中返回。
• 系統工具預設為開啟。 新代理程式自動獲得 current_time、ip_geo 和 weather（內置的 system MCP）——您無需列出它們；tools 是用於 額外 工具的。
• URL 中的名稱已進行 slug 處理。 知識庫 的名稱在創建時會轉換為 URL 安全的 slug（"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，請設置缺失的 alias（create_agent(alias=…) / PUT /agents/{name}/alias；租戶 alias 在控制台中 → 設置），而不是發送令牌鏈接。chat_url 仍適合嵌入和 QR 碼。

• 沒有網站——僅提供鏈接或 QR 碼（自由職業者、商店、傳單、名片）：交還 chat_url（全屏 托管聊天頁面——無需網站）和 qr_url（可打印的 QR 碼）。它是匿名的：無需登錄，每個訪客都通過其瀏覽器被記住，因此常客會被識別。
• 他們自己的網站：提供 embed_snippet（</body> 之前的一行代碼，用於浮動小部件），或 chat_url 用於鏈接/iframe。
• Telegram / WhatsApp：在控制台中按頻道設置（代理程式 → 集成 → Telegram / WhatsApp）；將他們引導至那裡。

回報結果。 交還他們可以立即打開和測試的 實際鏈接（chat_url，如果他們沒有網站則包括 qr_url），以及用於審查的代理程式控制台頁面—— https://console.agent4.io/#/agents/Support。不是「已發布」——而是鏈接。