라이브킷을 사용할때 web에서 room에 접속할때 agent metadata를 넘겨주는 방...
# ask-ail
limited-planet-15554
12/26/2025, 9:19 AM라이브킷을 사용할때 web에서 room에 접속할때 agent metadata를 넘겨주는 방법이 있어?
t
tall-airline-16756
12/26/2025, 9:19 AMThanks for reaching out, Dan(송희웅). I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
tall-airline-16756
12/26/2025, 9:20 AM요청하신 부분(웹에서 room 접속 시 agent metadata 전달 방법)에 대해 답드릴게요.
가능합니다. 웹 클라이언트가 room에 접속할 때 사용하는 액세스 토큰(access token)에 RoomConfiguration의
RoomAgentDispatchroomJoinagents Copy code
const at = new AccessToken();
at.identity = 'user-identity';
at.addGrant({ roomJoin: true, room: 'my-room' });
at.roomConfig = new RoomConfiguration({
agents: [
new RoomAgentDispatch({
agentName: 'my-agent',
metadata: '{"user_id":"12345","user_name":"Alice"}'
})
]
});
const token = await at.toJwt(); Copy code
export default defineAgent({
entry: async (ctx: JobContext) => {
const metadata = JSON.parse(ctx.job.metadata);
// metadata.user_id, metadata.user_name 사용
}
});l
limited-planet-15554
12/26/2025, 9:33 AM그런데 코드를 보니깐 Nextjs 웹 클라이언트에서
"useSession" 을 통해서 api 를 호출해 "participantToken" 를 발급할때, 그때 RoomAgentDispatch 를 통해 metadata를 넘기는데, 웹 클라이언트에서 useSession 을 통해 metadata 를 어떻게 넘기지?
t
tall-airline-16756
12/26/2025, 9:33 AM좋은 질문이에요 — Next.js 클라이언트의 `useSession`으로 받은 유저 정보(또는 세션 데이터)를 API 호출에 포함시켜 서버에서 `RoomAgentDispatch.metadata`로 넣어주면 됩니다. 요점과 예시 코드를 간단히 드릴게요.
1) 클라이언트(Next.js): `useSession`에서 필요한 사용자 필드(예: id, name)를 읽어 POST 바디나 헤더로 전송
Copy code
// pages or components
import { useSession } from "next-auth/react";
const joinRoom = async () => {
const { data: session } = useSession();
const metadata = {
user_id: session?.user?.id,
user_name: session?.user?.name,
};
const res = await fetch("/api/participant-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ room: "my-room", metadata }),
});
const { token } = await res.json();
// token으로 LiveKit 접속
}; Copy code
// pages/api/participant-token.ts
import { NextApiRequest, NextApiResponse } from "next";
import { AccessToken, RoomConfiguration, RoomAgentDispatch } from "livekit-server-sdk"; // 예시 임포트
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const { room, metadata } = req.body;
const at = new AccessToken();
at.identity = "participant-" + Math.random().toString(36).slice(2);
at.addGrant({ roomJoin: true, room });
at.roomConfig = new RoomConfiguration({
agents: [
new RoomAgentDispatch({
agentName: "my-agent",
metadata: JSON.stringify(metadata),
}),
],
});
const token = await at.toJwt();
res.status(200).json({ token });
}l
limited-planet-15554
12/26/2025, 9:35 AMimport {
RoomAudioRenderer,
SessionProvider,
StartAudio,
useSession,
} from '@alert-easter-19258/components-react';
const tokenSource = useMemo(() => {
return typeof process.env.NEXT_PUBLIC_CONN_DETAILS_ENDPOINT === 'string'
? getSandboxTokenSource(appConfig)
: TokenSource.endpoint('/api/connection-details');
}, [appConfig]);
const session = useSession(
tokenSource,
appConfig.agentName ? { agentName: appConfig.agentName } : undefined
);
코드가 이렇게 되어 있어! useSession 은 라이브킷의 컴포넌트야
t
tall-airline-16756
12/26/2025, 9:35 AM좋습니다 — 주신 코드(라이브킷의
useSessionuseSessionmetadata/api/connection-detailsroomConfig.agentsJSON.stringify(metadata)JobContext.job.metadataTokenSource.endpoint('/api/connection-details')l
limited-planet-15554
12/26/2025, 9:41 AMconst tokenSource = useMemo(() => {
return TokenSource.endpoint('/api/connection-details');
}, [appConfig]);
const session = useSession(
tokenSource,
appConfig.agentName ? { agentName: appConfig.agentName } : undefined
);
useSession 에서 POST 로 /api/connection-details 를 호출하는데, 이때 metadata 를 넘길수 있는 방법을 알려줘
t
tall-airline-16756
12/26/2025, 9:41 AM좋은 질문이에요 — 핵심: 기본 `TokenSource.endpoint('/api/connection-details')`가 내부 호출에 커스텀 바디를 보낼 수 없다면, 클라이언트에서 metadata를 포함해 토큰을 요청하도록 TokenSource를 직접 구현하거나, 쿼리/헤더에 metadata를 실어 서버에서 읽도록 해야 합니다. 아래에 두 가지 실용적 방법과 예시 코드를 드릴게요.
옵션 A — 커스텀 TokenSource 구현 (권장)
• `useSession`에 넘기는 TokenSource를 직접 만들어 POST 바디에 metadata를 포함해 호출하도록 구현합니다.
예시 (Next.js, TS/React):
Copy code
import { TokenSource } from "@livekit/components-react";
// custom token source
function createCustomTokenSource(getMetadata: () => any) {
return {
getToken: async () => {
const metadata = getMetadata();
const res = await fetch("/api/connection-details", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ metadata }),
});
const json = await res.json();
return { token: json.token, serverUrl: json.serverUrl };
},
} as TokenSource;
}
// 사용
const tokenSource = useMemo(() => {
return createCustomTokenSource(() => ({
user_id: session?.user?.id,
user_name: session?.user?.name,
}));
}, [session]); Copy code
import { getServerSession } from "next-auth"; // 사용중이면
export default async function handler(req, res) {
const session = await getServerSession(req, res, authOptions);
if (!session) return res.status(401).json({ error: "Not authenticated" });
const metadata = { user_id: session.user.id, user_name: session.user.name };
// AccessToken 생성 후 metadata를 RoomAgentDispatch 또는 at.metadata에 넣음
// res.json({ token, serverUrl });
}RoomAgentDispatch.metadata2 Views