Confident Tracing 스킬

Confident Tracing 스킬 (Confident Tracing Skill)

에이전트에게 confident-trace 통합과 커스텀 스팬으로 Python·TypeScript AI 앱을 계측하는 법을 가르치는 스킬 문서예요. 이 문서에서는 스킬이 언제 발동하는지, 설치 방법, 코드베이스에서 바뀌는 것, 그리고 자주 묻는 질문을 설명할게요.

출처: 문서

본문

개요 (Overview)

confident-tracing Agent Skill은 코딩 에이전트에게 Python 또는 TypeScript confident-trace SDK로 AI 애플리케이션을 계측해서, 모든 모델 호출·검색·도구 호출·에이전트 단계가 Confident AI에 스팬 단위로 나타나게 하는 법을 가르쳐요.

범위는 의도적으로 좁아요: 잘 만들어진 트레이스를 생성하는 것. 이 스킬은 언어, 프레임워크, 모델 제공자, 에이전트 SDK, 게이트웨이, 번들러, 기존 OpenTelemetry 설정을 감지하고, 지원되는 통합을 선호하며, 필요하면 커스텀 @span, span(), withSpan() 계측으로 폴백하고, 유용한 트레이스 컨텍스트를 추가해요. 지표 붙이기와 평가 실행은 deepeval 스킬의 몫이에요.

언제 발동하나요?

이 스킬은 다음과 같은 프롬프트에서 활성화돼요:

Instrument this app with Confident Trace.
Add automatic tracing to my LangGraph agent.
Add @span around the custom retriever in this Python RAG pipeline.
Make my TypeScript agent's OpenAI calls appear in Confident AI.

DeepEval 테스트 스위트, 데이터셋, 골든, 지표를 만들지는 않아요. confident-trace 패키지 없이 원시 벤더 중립 OpenTelemetry 내보내기는 confident-otel을 사용해요.

설치 (Installation)

Skills CLI

Cursor, Claude Code, Codex, Windsurf, OpenCode 등 Skills 호환 어시스턴트에서 작동해요:

npx skills add confident-ai/confident-trace --skill "confident-tracing"

Claude Code (플러그인)

Confident Trace 플러그인은 confident-tracing과 confident-otel을 둘 다 번들해요:

/plugin marketplace add confident-ai/confident-trace
/plugin install confident-trace@confident-trace-plugins
/reload-plugins

수동 복사

스킬 폴더를 에이전트의 스킬 디렉토리에 복사해요:

git clone https://github.com/confident-ai/confident-trace
cp -r confident-trace/skills/confident-tracing .claude/skills/

사전 조건 (Prerequisites)

Python 3.10+ 또는 Node.js 22+
애플리케이션에 confident-trace 설치
Confident AI로 내보내기 위한 프로젝트 범위 CONFIDENT_API_KEY

코드베이스에서 바뀌는 것

트레이싱 요청하기

에이전트는 언어와 AI 스택을 감지하고, 현재 confident-trace 통합 문서를 읽으며, 지원되는 통합이 있으면 자동 계측을 선택해요.

Instrument this agent with confident-trace and send its traces to Confident AI.

SDK 초기화

Python에서 에이전트는 confident-trace를 설치하고 provider·프레임워크 호출 전에 init()을 한 번 호출해요:

import confident_trace as ct

ct.init()

TypeScript에서 자동 계측은 엔트리 파일의 init()과 Node 등록 프리로드 둘 다 필요해요:

import { init } from "confident-trace";

const tracing = init();

node --import confident-trace/register dist/index.js

통합이 못 하는 곳에 커스텀 스팬 추가

에이전트는 애플리케이션 소유 경계나 지원되지 않는 구성 요소 주변에만 커스텀 스팬을 추가해요. 지원되는 다섯 가지 스팬 유형(agent, llm, retriever, tool, custom) 중 하나를 사용해요.

Python 예시

import confident_trace as ct

@ct.span(type="retriever")
def retrieve(query: str) -> list[str]:
    documents = search(query)
    ct.update_span(input=query, retrieval_context=documents)
    return documents

TypeScript 예시

import { span, updateSpan } from "confident-trace";

const retrieve = span(
  { name: "retrieve", type: "retriever" },
  async (query: string) => {
    const documents = await search(query);
    updateSpan({ input: query, retrievalContext: documents });
    return documents;
  },
);

트레이스·대화 컨텍스트 추가

에이전트는 update_trace() 또는 updateTrace()를 트레이스 입력, 출력, 태그, 메타데이터, user_id / user, customer_id / customer, 스레드 ID, 턴 ID, 환경에 사용해요. 각 대화 턴이 같은 스레드와 연결을 유지하면서 별도 트레이스를 시작해야 할 때는 turn()을 사용해요.

with ct.turn(thread_id="chat-42", turn_id="2", input=user_input):
    answer = run_agent(user_input)
    ct.update_trace(output=answer)

트레이스 검증

에이전트는 진행 중인 작업과 스트림을 마친 뒤 플러시하거나 종료하고, Confident AI에서 트레이스 계층을 검증해요:

export CONFIDENT_API_KEY="confident_us_proj_..."
python main.py

API 키, 자격 증명, 승인되지 않은 민감 데이터는 절대 기록하지 마세요. 패키지 소유 콘텐츠를 캡처하면 안 될 때 Python에서는 capture_content=False를, TypeScript에서는 captureContent: false를 설정해요.

자주 묻는 질문 (FAQs)

이 스킬이 지원하는 통합은 무엇인가요?

이 스킬은 현재 confident-trace SDK가 구현한 통합을 다뤄요. Python에는 OpenAI, Anthropic, Google GenAI, Bedrock, LangChain, LangGraph, OpenAI Agents, CrewAI, LlamaIndex, Agno, smolagents, Google ADK, Microsoft Agent Framework, Pydantic AI, Strands, AgentCore, Claude Agent SDK, 지원되는 LLM 게이트웨이가 포함돼요. TypeScript에는 OpenAI, Anthropic, Google GenAI, Vercel AI SDK, LangChain, LangGraph, Mastra, OpenAI Agents, 지원되는 게이트웨이가 포함돼요. 이 스킬은 설정 코드를 작성하기 전에 저장소의 현재 통합 문서를 읽어요.

백엔드 전체를 트레이싱하나요?

아니요. AI 구성 요소만 계측해요: 에이전트 루프, 모델 호출, 검색, 도구 호출, 그리고 이를 조직하는 애플리케이션 경계.

Python과 TypeScript 둘 다에서 작동하나요?

네. Python은 @span과 스팬 컨텍스트 매니저를 사용해요. TypeScript는 span()과 withSpan()을 사용하고 자동 계측에 confident-trace/register 프리로드가 필요해요.

지표를 붙이거나 평가를 실행하나요?

아니요. 잘 만들어진 트레이스를 생성하는 것이 작업의 끝이에요. 평가 스위트, 데이터셋, 지표, 테스트 실행은 deepeval 스킬을 사용해요.

다음 단계

LLM 트레이싱 퀵스타트

이 스킬이 자동화하는 기반 Confident Trace 설정을 확인해요.

Confident OpenTelemetry 스킬

Confident Trace SDK를 원하지 않을 때 원시 OpenTelemetry를 내보내요.

Confident Tracing 스킬