LiveKit Agents

실시간 음성·다중모달 에이전트를 만들고 있다면, 그 실행도 추적하고 싶겠죠. LiveKit Agents는 Python과 TypeScript로 실시간 음성·다중모달 에이전트를 만드는 프레임워크예요. 통합은 OpenTelemetry를 통해 동작합니다. LiveKit가 세션·턴·모델 요청·도구·말하기 타이밍에 대한 네이티브 스팬을 만들면, confident-trace가 그 스팬을 부모-자식 관계까지 보존한 채 Confident AI로 내보내줘요.

출처: 문서

본문

개요

LiveKit Agents는 Python과 TypeScript로 실시간 음성·다중모달 에이전트를 만드는 프레임워크입니다.

이 통합은 OpenTelemetry로 동작합니다. LiveKit는 세션, 턴, 모델 요청, 도구, 말하기 타이밍에 대한 네이티브 스팬을 만들어요. Confident AI의 OpenTelemetry 네이티브 추적 SDK인 confident-trace가 그 스팬을 부모-자식 관계까지 보존한 채 Confident AI로 내보냅니다.

init()을 에이전트 파일 맨 위에 두세요. 에이전트를 감싸거나 각 세션에 추적 콜백을 추가할 필요는 없어요.

Runtime	Requirements	Setup
Python	Python 3.10+, `livekit-agents` (tested with 1.8.3)	Call `init()` at module scope, before starting the agent server
TypeScript	Node.js 22+, `@livekit/agents >=1.9.0 <2`	Call `init()` at module scope and start the worker with the preload

자동 계측

의존성 설치

기존 LiveKit 에이전트 프로젝트에 confident-trace를 추가하세요. 에이전트가 이미 쓰는 모델 플러그인은 유지하면 돼요.

Python

pip install confident-trace 'livekit-agents==1.8.3'

TypeScript

npm install confident-trace '@livekit/agents@>=1.9.0 <2'

yarn add confident-trace '@livekit/agents@>=1.9.0 <2'

새 에이전트를 시작한다면 먼저 LiveKit 빠른 시작을 따라가고, 그 다음 아래 추적 설정을 추가하세요.

API 키 설정

Confident AI Project API key를 받아 에이전트 서버와 워커 프로세스에서 쓸 수 있게 하세요.

export CONFIDENT_API_KEY="<your-confident-project-key>"

기존 LiveKit 자격 증명과 모델 프로바이더 키는 평소처럼 유지하세요.

EU 리전 사용자는 트레이스가 우리 EU 서버로 가도록 EU OTEL 엔드포인트를 설정하세요.
export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

에이전트 계측

서버를 시작하기 전에, LiveKit이 각 작업에 대해 로드하는 파일의 모듈 스코프에 init()을 추가하세요. 기존 세션·모델·도구 구성은 유지하면 돼요.

Python

from confident_trace import init
from livekit.agents import AgentServer, JobContext, cli

init()
server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    await ctx.connect()
    # Keep your existing AgentSession setup and agent logic here.


if __name__ == "__main__":
    cli.run_app(server)

TypeScript

import { fileURLToPath } from "node:url";
import { init } from "confident-trace";
import { cli, defineAgent, ServerOptions } from "@livekit/agents";
import type { JobContext } from "@livekit/agents";

init();

export default defineAgent({
  entry: async (ctx: JobContext) => {
    await ctx.connect();
    // Keep your existing AgentSession setup and agent logic here.
  },
});

cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));

LiveKit는 작업을 에이전트 파일을 로드하는 별도의 워커 프로세스에서 실행해요. init()을 모듈 스코프에 두어, LiveKit이 작업의 루트 스팬을 만들기 전에 추적이 준비되게 하세요. Python에서 entrypoint()나 if __name__ == "__main__" 블록 안에만 두면 워커에서 그 설정을 놓치게 됩니다. LiveKit의 작업 수명 주기를 참고하세요.

에이전트 실행

Python

python agent.py dev

TypeScript

컴파일된 에이전트를 confident-trace/register preload로 실행하세요.

node --import confident-trace/register dist/agent.js dev

경로는 빌드 출력에 맞게 조정하세요. tsx로 TypeScript 소스를 실행하는 프로젝트라면 이렇게 하세요.

node --import confident-trace/register --import tsx agent.ts dev

preload가 자동 계측을 설치하고, init()이 export를 구성합니다. 둘 다 필요해요. 프로덕션과 워커 프로세스에서도 preload를 켜 둔 채 유지하세요.

프로덕션에는 dev 대신 start를 사용하세요. 평소처럼 에이전트에 연결한 다음, Confident AI 프로젝트에서 Observatory를 열어 트레이스를 확인하세요.

Confident는 LiveKit이 작업 정리를 마친 후, 비동기 shutdown 콜백이 완료한 스팬을 포함해 보류 중인 스팬을 플러시합니다. 별도 플러시 콜백을 추가할 필요가 없어요. 정상적인 워커 종료를 허용하세요. 강제 프로세스 종료는 보류 중인 스팬을 잃을 수 있어요.

무엇이 포착되나

통합은 LiveKit이 만드는 네이티브 스팬을 LiveKit 라벨로 내보냅니다.

세션·작업 수명 주기 — 호출 내 작업의 계층과 타이밍
사용자·에이전트 턴 — 세션 내의 대화 활동
모델 요청 — 모델 플러그인이 내보낼 때의 모델 상세와 토큰 사용량
도구 호출 — 도구 실행과 LiveKit이 기록한 속성
말하기 타이밍 — 말하기, 턴 종료 감지, 사용 가능할 때의 텍스트-음성 스팬
오류 — 네이티브 스팬에 기록된 오류 상태

LiveKit의 네이티브 모델 스팬이 Confident의 프로바이더를 통해 내보내질 때, 통합은 중첩된 프로바이더 스팬을 억제해서 각 모델 호출이 한 번만 기록돼요. 그 네이티브 모델 스팬 밖의 지원되는 프로바이더 호출은 여전히 따로 추적할 수 있습니다.

포착되는 필드는 LiveKit과 모델 플러그인에 달려 있어요. 대화 기록과 음성 텍스트는 LiveKit의 네이티브 lk.* 속성에 남아 있고, 아직 Confident AI의 전용 입출력 표시로 매핑되지 않습니다. 스팬을 내보낸다고 모든 네이티브 필드가 전용 UI 필드에 나타나는 건 아니에요.

트레이스 스팬 속성 설정

작업 엔트리포인트 안에서, 세션을 시작하기 전에 트레이스 컨텍스트로 태그, 메타데이터, 사용자 ID, 고객 ID를 추가하세요. 추가 스팬은 만들지 않아요. LiveKit이 엔트리포인트를 호출할 때 이미 작업 스팬이 활성이므로, 이 속성들이 그 스팬의 설정되지 않은 필드를 채웁니다.

init()을 위처럼 모듈 스코프에 두세요. 아래 예제에서 session과 agent는 내가 구성한 기존 AgentSession과 에이전트입니다. 샘플 ID를 애플리케이션 값으로 바꾸세요.

Python

from confident_trace import trace_context


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    async with trace_context(
        tags=["support"],
        metadata={"release": "2026-09"},
        user_id="user-42",
        customer_id="customer-7",
    ):
        await ctx.connect()
        await session.start(room=ctx.room, agent=agent)

TypeScript

import { traceContext } from "confident-trace";

export default defineAgent({
  entry: async (ctx: JobContext) => {
    await traceContext(
      {
        tags: ["support"],
        metadata: { release: "2026-09" },
        userId: "user-42",
        customerId: "customer-7",
      },
      async () => {
        await ctx.connect();
        await session.start({ room: ctx.room, agent });
      },
    );
  },
});

호출 수준 속성을 엔트리포인트 시작 부분에 설정하세요. 나중의 도구·이벤트 콜백 안의 트레이스 컨텍스트는 그 위치의 활성 스팬에 적용되며, 이전 작업 스팬을 자동으로 찾아 갱신하지 않아요. 컨텍스트는 워커 프로세스에 국한되므로, 서버 실행이나 작업을 디스패치하는 클라이언트를 감싼다고 그 속성이 워커로 전달되지 않습니다.

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

콘텐츠 프라이버시

LiveKit은 네이티브 스팬의 콘텐츠를 제어합니다. 워커를 시작하기 전에 이걸 설정하면 LiveKit의 대화 콘텐츠 포착을 끌 수 있어요.

export LIVEKIT_TELEMETRY_ALLOW_PII=0

Confident의 capture_content / captureContent와 삭제 옵션은 Confident가 만든 스팬에만 적용되며, LiveKit의 네이티브 스팬 속성을 지우지 않아요. LiveKit을 직접 계측된 모델 클라이언트와 함께 쓸 때는 두 레이어를 모두 구성하세요.

LiveKit 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. LiveKit 식별자는 Python·TypeScript 모두 "livekit"입니다. 이를 빼면 어댑터가 비활성화되고, 빈 목록은 모든 자동 계측을 비활성화합니다.

Python

from confident_trace import init

init(instrumentations=())

TypeScript

import { init } from "confident-trace";

init({ instrumentations: [] });

이렇게 하면 Confident의 자동 어댑터가 꺼지고, LiveKit 정리 플러시도 꺼집니다. LiveKit은 구성된 프로바이더를 통해 자체 네이티브 OpenTelemetry 스팬을 여전히 만들어 낼 수 있어요. LiveKit은 선택 사항입니다 — 설치하지 않은 애플리케이션은 init()을 정상적으로 사용할 수 있어요.

다음 단계

Online Evals

지원되는 트레이스·스팬 입력이 Confident AI에 도착하는 대로 평가하세요.

Troubleshooting

시작 구성, export, 누락된 트레이스를 확인하세요.

더 알아보기

Online Evals — 도착하는 트레이스·스팬을 평가
Troubleshooting — 설정·export·누락 트레이스 확인