文件

身分驗證

透過為已登入的使用者簽署 JWT 來驗證是誰在聊天。Agentkit 會驗證權杖，並將對話連結至聯絡人。

身分驗證讓 Agentkit 知道是誰在聊天。你的後端會為已登入的使用者簽署一組短效 JWT，小工具再將這組權杖交給 Agentkit；Agentkit 驗證後，會將對話連結至聯絡人。

這項機制屬於身分資料補充與防冒用機制，絕非存取關卡。權杖遺失、過期或無效時，訪客只會以匿名身分繼續聊天——聊天功能絕不會被封鎖。

注意：身分權杖會攜帶使用者的私人資料。務必在伺服器端簽署，切勿在用戶端 JavaScript 中簽署——在瀏覽器中簽署會暴露你的密鑰。

運作方式

  1. 使用者登入你的應用程式。
  2. 你的後端會產生一組短效 JWT，並以你代理程式的簽署密鑰進行簽署。
  3. 你再將權杖交給小工具（可以在小工具載入前，或在執行階段進行）。
  4. 小工具會在每個聊天請求中一併傳送權杖。
  5. Agentkit 會驗證簽章與宣告內容，接著依權杖的主體（subject）建立或更新聯絡人，並將對話連結至該聯絡人。

啟用驗證

  1. 開啟你的代理程式，前往設定 → 身分。
  2. 開啟驗證已登入的訪客（JWT）。
  3. 複製簽署密鑰。

簽署密鑰僅能用於伺服器端——請將它存放在環境變數中，切勿在用戶端程式碼中外流。重新產生密鑰後，所有以舊密鑰簽署的權杖都會立即失效。

權杖規格

請以 HS256 演算法簽署權杖。其他演算法（包括 alg: none 及非對稱金鑰）一律會被拒絕。

宣告內容

宣告是否必填備註
sub（或 user_id）是你應用程式中不會變動的使用者 ID。請使用穩定的內部 ID——不可使用電子郵件、使用者名稱或 Agentkit ID。若 sub 與 user_id 同時存在，兩者必須一致。
exp是到期時間。請使用短效權杖（約 1 小時）。若 exp 超過目前時間 24 小時以上，該權杖會被拒絕。
aud建議填寫將權杖綁定至此代理程式：agentkit:chatbot:{chatbotId}。若有提供此欄位，其值必須相符。
email否會儲存於聯絡人資料中。
name否會儲存於聯絡人資料中。
phonenumber否會儲存於聯絡人的 phone 欄位中。
custom_attributes否用於存放任何額外資料的物件（例如方案、公司、Stripe ID 等）。

權杖中只有 email、name、phonenumber 與 custom_attributes 會被讀取。其他任何頂層宣告都會被忽略——額外或整合用的資料請放在 custom_attributes 內。

限制

  • email、name、phonenumber：各欄位最多 1024 個字元。
  • custom_attributes：最多 8192 位元組、50 個鍵，且巢狀結構最深 5 層。

超出這些限制的權杖會被視為匿名（失敗會被記錄），而不會因此封鎖聊天。

簽署權杖

任何 JWT 函式庫都適用（jsonwebtoken、PyJWT 等）——你只需要產生一組包含上述宣告的 HS256 權杖即可。以下範例使用 jose，它同樣能在邊緣執行環境（Vercel Edge、Cloudflare Workers、Deno）中運作：

// On YOUR backend, mint a short-lived JWT for your logged-in user.
import { SignJWT } from 'jose';

const secret = new TextEncoder().encode(
  process.env.AGENTKIT_CHATBOT_IDENTITY_SECRET,
);

const token = await new SignJWT({
  // Optional private profile claims — stored on the Contact, never shown to the
  // bot. ONLY these keys are read: email, name, phonenumber, custom_attributes.
  // Put extra/integration data (Stripe ids, plan, company, …) in custom_attributes.
  email: user.email,
  name: user.name,
  phonenumber: user.phone, // maps to the Contact's "phone"
  custom_attributes: {
    plan: user.plan,
    stripe_id: user.stripeCustomerId,
  },
})
  .setProtectedHeader({ alg: 'HS256' })
  .setSubject(user.id) // immutable id from YOUR system (not email/username)
  .setIssuedAt()
  .setExpirationTime('1h') // short-lived; this is a browser bearer token
  .setAudience('agentkit:chatbot:YOUR_CHATBOT_ID')
  .sign(secret);

同一段程式碼片段（已預先填入你代理程式的 audience 值）也會顯示在設定 → 身分頁面中。

# Python example using PyJWT
import jwt, os, time

token = jwt.encode(
    {
        "sub": user.id,
        "email": user.email,
        "name": user.name,
        "phonenumber": user.phone,
        "custom_attributes": {"plan": user.plan},
        "aud": "agentkit:chatbot:YOUR_CHATBOT_ID",
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600,
    },
    os.environ["AGENTKIT_CHATBOT_IDENTITY_SECRET"],
    algorithm="HS256",
)

將權杖傳遞給小工具

請在小工具的指令碼載入之前設定好權杖（例如：在伺服器端將它注入頁面）：

<script>
  window.agentkitUserConfig = { token: 'YOUR_SIGNED_TOKEN' };
</script>

在單頁應用程式（SPA）中，請在執行階段更新或清除身分資訊——例如在使用者登入或登出之後：

// After the user logs in (or the token is refreshed):
window.agentkit('identify', { token: newToken });

// After the user logs out:
window.agentkit('resetUser');

小工具會自動將權杖附加到每個聊天請求上；你不需要自行設定任何標頭。

隱私權

已驗證的個人資料欄位（email、name、phonenumber、custom_attributes）僅會儲存在伺服器端的聯絡人資料中。這些欄位絕不會被注入代理程式的提示詞或 RAG 內容中，也絕不會透過任何公開端點回傳。代理程式並不會「看到」自己正在與誰對話。

驗證行為

驗證機制絕不會封鎖聊天。訪客永遠都能與代理程式對話；唯一的差異在於是否連結了聯絡人。

情況結果
沒有權杖匿名訪客。不會連結聯絡人。（並非錯誤。）
權杖有效已驗證。建立或更新聯絡人，並連結至此次對話。
簽章無效／權杖格式錯誤匿名。失敗會被記錄。
權杖已過期匿名。失敗會被記錄。
aud 與此代理程式不符匿名。失敗會被記錄。
個人資料宣告超出限制匿名。失敗會被記錄。

其他存取控制仍然適用

身分驗證與誰能載入小工具是兩件獨立的事。網域限制與可見性設定仍會各自獨立生效。

後續步驟