向 Managed Deep Agents 添加身份

使用 LangSmith API 密钥、Supabase 或你自己的后端对 Managed Deep Agents 部署的调用方进行身份验证。

身份控制谁可以调用你的托管 deep agent，例如启动运行或发送消息的应用和 SDK 客户端。

NOTE

Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。

将身份声明放在项目根目录：

my-agent/
  agent.py
  identity.py

有关完整项目布局，请参阅项目结构。

选择身份提供程序

默认情况下，mda init 要求调用方提供 LangSmith API 密钥。任何拥有该密钥的人都可以使用同一个部署，并可能看到相同的线程。要为每个登录的最终用户提供私密对话，请改用 Supabase：

目标	使用
为 SDK 客户端、脚本和服务锁定部署	LangSmith API 密钥（默认）
由 Managed Deep Agents 验证的、具有私密聊天的已登录最终用户	Supabase
已由你自己的 API 验证的、具有私密聊天的已登录最终用户	你自己的后端

Supabase 和后端身份都会为每个最终用户提供私密线程。区别在于谁验证用户。使用 Supabase 时，浏览器发送其访问 token，由 Managed Deep Agents 验证。使用后端身份时，你的 API 验证用户并断言生成的用户 ID。

更多信息请参阅项目结构。

NOTE

在托管部署上，LangSmith Studio 通过单独的工作区身份验证路径访问部署。无论你选择哪种身份提供程序，拥有 LangSmith 工作区 API 访问权限的调用方都可以读取和搜索部署中的每个线程。该调用方无法修改最终用户拥有的线程。因此，按用户隐私是针对最终用户的，而不是针对 LangSmith 工作区成员。

使用 LangSmith API 密钥配置身份

mda init 会作为安全默认值搭建此身份提供程序。调用方必须提供有效的 LangSmith 工作区 API 密钥。Managed Deep Agents 会向 LangSmith Cloud 验证该密钥。

from managed_deepagents import auth, define_identity

identity = define_identity(auth=auth.langsmith_api_key())

客户端将密钥作为 x-api-key 发送。你无需向项目 .env 添加验证端点或租户设置。LangSmith Cloud 会提供这些内容。

WARNING

任何拥有该密钥的人都可以访问部署，因此请将密钥视为机密。此默认设置不会为每个最终用户提供私密线程。如果 Alice 不能看到 Bob 的线程，请使用 Supabase 或你自己的后端。

使用 Supabase 配置身份

当浏览器或其他客户端以已登录实体的身份调用部署时，请使用 Supabase。每个用户都会获得私密线程。Managed Deep Agents 会为你配置该所有权。有关底层 LangSmith Deployment 模式的更多信息，请参阅使对话私密。

Enable auth in Supabase

在 Supabase 仪表板中，启用你将使用的身份验证提供程序（例如电子邮件/密码）。

Copy the project reference

复制项目引用：项目 URL 中 .supabase.co 之前的子域名。

Declare identity

使用该项目引用声明身份：

from managed_deepagents import auth, define_identity

identity = define_identity(
    auth=auth.supabase(project_ref="your-project-ref"),
)

对于自定义身份验证域，请传递 url 而不是项目引用。

Send the access token from the client

在客户端应用中，设置 Supabase 项目 URL 和可发布密钥（在 Supabase 仪表板中标记为 anon）。让用户登录，然后在每次部署请求中发送访问 token：

import httpx

response = httpx.post(
    f"{deployment_url}/threads/{thread_id}/runs",
    headers={
        "Authorization": f"Bearer {supabase_access_token}",
        "Content-Type": "application/json",
    },
    json=run_body,
)

可发布密钥（在 Supabase 仪表板中标记为 anon）仅用于客户端向 Supabase 登录。不要在此模式下发送 LangSmith API 密钥。Bearer token 就是调用方身份。

Managed Deep Agents 会根据从项目引用派生的项目 JWKS URL（https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json）验证 JWT。

NOTE

向现有部署添加 Supabase 身份不会向现有线程添加所有者元数据。在依赖基于身份的访问之前，请规划并测试迁移。

使用你自己的后端配置身份

当你的 API 已经验证用户并代表他们调用部署时，请使用后端身份。你的后端通过共享密钥证明自己的身份并指定调用方。只有在密钥匹配后，Managed Deep Agents 才会信任该名称，然后为每个命名用户提供私密线程。

在此模式下，浏览器永远不会直接访问部署。请求从浏览器发送到你的 API，再从你的 API 发送到部署。

Declare identity

from managed_deepagents import define_identity

identity = define_identity(auth="backend")

Generate the ingress secret

生成一个随机值，并将其作为 MDA_INGRESS_SECRET 添加到项目 .env：

openssl rand -hex 32

MDA_INGRESS_SECRET=<MDA_INGRESS_SECRET>

mda deploy 会将该值作为托管部署密钥转发。声明后端身份但没有此值的项目会在任何构建工作之前使部署预检失败，因为部署将以 401 拒绝每个请求。有关 .env 值如何到达部署的信息，请参阅部署。

Send both headers from your backend

在你自己的 API 中验证用户，然后在每次部署请求中发送密钥和解析后的用户 ID：

import httpx

response = httpx.post(
    f"{deployment_url}/threads/{thread_id}/runs",
    headers={
        "x-mda-ingress-secret": mda_ingress_secret,
        "x-mda-user-id": user_id,
        "Content-Type": "application/json",
    },
    json=run_body,
)

为 x-mda-user-id 使用与你自己的系统为该用户使用的相同标识符，并在会话之间保持稳定。线程和存储的凭据以此值为键，因此以新标识符到达的用户会访问不同的线程集。

WARNING

MDA_INGRESS_SECRET 是服务器端密钥。Managed Deep Agents 接受与有效密钥一起提供的任何 x-mda-user-id，因此任何持有该密钥的人都可以冒充任何用户。请将其保留在后端，绝不要放在浏览器代码、移动应用或客户端 bundle 中。

测试和部署

使用 mda dev 在本地测试项目，然后使用 mda deploy 部署。在 LangSmith 中打开部署追踪，以检查模型调用、工具调用、错误和延迟。

身份验证失败会返回 401。对于 LangSmith API 密钥默认值，确认客户端发送 x-api-key。对于 Supabase，确认客户端发送 Authorization: Bearer <access_token>，project_ref / projectRef 与你的 Supabase 项目匹配，并且调用方无法访问另一个用户的线程（403）。对于后端身份，确认你的 API 同时发送 x-mda-ingress-secret 和 x-mda-user-id，密钥与部署上的 MDA_INGRESS_SECRET 匹配，并且一个用户的标识符无法访问另一个用户的线程（403）。

---