Managed Deep Agents에 아이덴티티 추가하기

LangSmith API 키 또는 Supabase로 Managed Deep Agents 배포에 호출자를 인증할 수 있어요.

아이덴티티는 실행을 시작하거나 메시지를 보내는 앱 및 SDK 클라이언트 같은 관리형 딥 에이전트를 호출할 수 있는 대상을 제어합니다.

Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 지역에서만 사용할 수 있어요.

아이덴티티 선언을 프로젝트 루트에 넣으세요:

my-agent/
  agent.ts
  identity.ts

전체 프로젝트 레이아웃은 프로젝트 구조를 참고하세요.

출처: 문서

본문

아이덴티티 공급자 선택하기 (Choose the identity provider)

기본적으로 mda init은 호출자가 LangSmith API 키를 제시하도록 요구합니다. 해당 키가 있는 사람은 누구나 동일한 배포를 사용하고 동일한 스레드를 볼 수 있습니다. 로그인한 각 최종 사용자에게 비공개 대화를 제공하려면 대신 Supabase를 사용하세요:

목표 (Goal)	사용 (Use)
SDK 클라이언트, 스크립트, 서비스용 배포 잠그기	LangSmith API 키 (기본값)
개인 채팅이 있는 로그인 최종 사용자	Supabase

자세한 내용은 프로젝트 구조를 참고하세요.

LangSmith API 키로 아이덴티티 구성하기 (Configure identity with a LangSmith API key)

mda init은 이 아이덴티티 공급자를 안전한 기본값으로 스캐폴딩합니다. 호출자는 유효한 LangSmith 워크스페이스 API 키를 제시해야 합니다. Managed Deep Agents는 LangSmith Cloud로 키를 검증합니다.

import { auth, defineIdentity } from "managed-deepagents";

export const identity = defineIdentity({
  auth: auth.langsmithApiKey(),
});

클라이언트는 x-api-key로 키를 보냅니다. 프로젝트 .env에 검증 엔드포인트나 테넌트 설정을 추가할 필요가 없습니다. LangSmith Cloud가 그것을 제공합니다.

키가 있는 사람은 누구나 배포에 도달할 수 있으므로 키를 비밀로 취급하세요. 이 기본값은 각 최종 사용자에게 비공개 스레드를 제공하지 않습니다. Alice가 Bob의 스레드를 보면 안 되는 경우 Supabase를 사용하세요.

Supabase로 아이덴티티 구성하기 (Configure identity with Supabase)

브라우저 또는 다른 클라이언트가 로그인한 실체로 배포를 호출할 때 Supabase를 사용하세요. 각 사용자는 비공개 스레드를 얻습니다. Managed Deep Agents가 해당 소유권을 구성해 줍니다. 기본 LangSmith Deployment 패턴에 대한 자세한 내용은 대화를 비공개로 만들기를 참고하세요.

Supabase에서 인증 활성화하기 (Enable auth in Supabase)

Supabase 대시보드에서 사용할 인증 공급자(예: email/password)를 활성화합니다.

프로젝트 참조 복사하기 (Copy the project reference)

프로젝트 참조를 복사합니다: 프로젝트 URL에서 .supabase.co 앞의 하위 도메인.

아이덴티티 선언하기 (Declare identity)

해당 프로젝트 참조로 아이덴티티를 선언합니다:

import { auth, defineIdentity } from "managed-deepagents";

export const identity = defineIdentity({
  auth: auth.supabase({ projectRef: "your-project-ref" }),
});

커스텀 인증 도메인의 경우 프로젝트 참조 대신 url을 전달하세요.

클라이언트에서 액세스 토큰 보내기 (Send the access token from the client)

클라이언트 앱에서 Supabase 프로젝트 URL과 퍼블리셔블 키(Supabase 대시보드에서 anon으로 표시)를 설정합니다. 사용자를 로그인시킨 다음, 모든 배포 요청에 액세스 토큰을 보냅니다:

await fetch(`${deploymentUrl}/threads/${threadId}/runs`, {
  method: "POST",
  headers: {
    Authorization: *** ${supabaseAccessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(runBody),
});

퍼블리셔블 키(Supabase 대시보드에서 anon으로 표시)는 클라이언트가 Supabase에 로그인하기 위한 용도로만 사용됩니다. 이 모드에서는 LangSmith API 키를 보내지 마세요. Bearer 토큰이 호출자 아이덴티티입니다.

Managed Deep Agents는 프로젝트 참조에서 파생된 프로젝트의 JWKS URL(https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json)에 대해 JWT를 검증합니다.

기존 배포에 Supabase 아이덴티티를 추가해도 기존 스레드에 소유자 메타데이터가 추가되지는 않습니다. 해당 스레드에 대한 아이덴티티 기반 접근에 의존하기 전에 마이그레이션을 계획하고 테스트하세요.

테스트 및 배포 (Test and deploy)

mda dev로 프로젝트를 로컬에서 테스트한 다음 mda deploy로 배포합니다. LangSmith에서 배포 트레이스를 열어 모델 호출, 도구 호출, 오류, 지연시간을 검사하세요.

인증 실패는 401을 반환합니다. LangSmith API 키 기본값의 경우 클라이언트가 x-api-key를 보내는지 확인하세요. Supabase의 경우 클라이언트가 Authorization: Bearer <token>을 보내는지, project_ref / projectRef가 Supabase 프로젝트와 일치하는지, 그리고 호출자가 다른 사용자의 스레드(403)에 접근할 수 없는지 확인하세요.

더 알아보기 (Learn more)

이 문서들을 사용하기 — MCP를 통해 Claude, VSCode 등에 연결하여 실시간 답변을 받아 보세요.
GitHub에서 이 페이지 편집 또는 이슈 등록