핵심 요약

• 문제: Figma 공식 데스크톱 MCP 서버는 유료 플랜의 Dev/Full 좌석이 필요하고, 무료 원격 서버는 베타 이후 사용량 기반 유료 전환이 예고되어 있다.
• 해결: Figwright는 로컬 MCP 서버와 피그마 플러그인을 WebSocket 릴레이로 연결한다. 디자인 읽기·쓰기 112개 도구를 무료 플랜에서 쓸 수 있다.
• 검증 결과: npm 타르볼 sha512 무결성 일치, SLSA provenance(attestation) 확인, 원격 텔레메트리 없음, 릴레이 포트의 Origin/Host 헤더 검증 동작을 직접 확인했다.
• 주의: 쓰기 도구는 피그마 파일을 변경하고 내보내기 도구는 에이전트가 지정한 경로에 파일을 쓴다. 악성 디자인이나 프롬프트 인젝션에 악용될 수 있으므로 MCP 클라이언트의 도구 승인 설정이 실제 방어선이다.
• 판정: 피그마를 쓰는 프론트엔드 개발자에게 유용하고, 피그마를 디자인 소스로 쓰지 않는 백엔드 개발자는 설치할 이유가 없다.

Figwright란 무엇인가

이 표의 스타 수치는 2026-09-13 관측값이며, 증가율은 직전 스냅숏(2026-09-10 717개)과의 실측 차이다. 저장소 생성 90일 미만의 신생 프로젝트라 장기 추이는 아직 판단할 수 없다.

왜 필요한가: 공식 Figma MCP의 제약

Figma 공식 문서에 따르면 두 가지 제약이 있다.

1. 데스크톱 MCP 서버는 유료 플랜의 Dev 또는 Full 좌석이 필요하다. 무료·프로 플랜의 일반 시트로는 로컬 서버를 쓸 수 없다.
2. 원격 서버는 모든 좌석에서 쓸 수 있지만 “AI 에이전트 지원은 결국 사용량 기반 유료 기능이 될 것”이라고 명시되어 있다. 현재는 베타 무료지만 과금 전환이 예고된 상태다.

또한 공식 서버의 코드 생성은 읽기 중심이다. 에이전트가 피그마 캔버스에 직접 프레임·텍스트·컴포넌트를 만들거나 수정하는 쓰기 작업은 Figwright의 차별점이다.

작동 구조와 데이터 경계

Figwright는 세 부분으로 구성된다.

Claude Code / Codex / Cursor
        │ stdio (MCP)
        ▼
@figwright/mcp 서버 (npx 실행)
        │ 로컬 WebSocket · msgpack (127.0.0.1:3055)
        ▼
피그마 데스크톱/브라우저의 Figwright 플러그인
        │ Figma Plugin API
        ▼
      캔버스

서버·릴레이·플러그인이 모두 내 컴퓨터에서 실행된다. 디자인 파일이 외부로 전송되지 않고, API 키도 필요 없다. 외부 호스트로 나가는 통신 코드가 번들에 없음을 직접 확인했다.

루프백 포트라도 웹 페이지가 로컬 포트에 접근할 수 있으므로(DNS 리바인딩), 릴레이는 두 가지 검증을 한다. Host 헤더가 루프백을 지칭해야 하고, Origin 헤더는 플러그인의 샌드박스 핸드셰이크만 허용한다.

Claude Code 설치 방법

Node.js 20.19+ 또는 22.12+가 필요하다 (18/21, 22.0~22.11은 미지원). 프로젝트 루트의 .mcp.json에 추가한다.

{
  "mcpServers": {
    "figwright": {
      "command": "npx",
      "args": ["-y", "@figwright/mcp@latest"]
    }
  }
}

설치 시 바뀌는 것은 설정 파일의 서버 항목뿐이다. 전역 설치나 상주 프로세스는 없다.

피그마 플러그인 설치

플러그인은 아직 피그마 커뮤니티 마켓에 없다. GitHub 릴리스에서 zip을 받아 수동 등록한다.

1. https://github.com/awdr74100/figwright/releases/latest 에서 figwright-plugin-v0.5.0.zip을 내려받아 압축을 푼다.
2. 피그마 데스크톱 앱에서 메뉴 → Plugins → Development → Import plugin from manifest… 를 선택하고 압축 푼 폴더의 manifest.json을 지정한다.
3. Plugins → Development → Figwright를 열면 로컬 서버에 자동 연결되어 Connected 상태가 된다.

데스크톱 앱이 필요한 이유는 개발 모드 플러그인 임포트가 데스크톱에서만 지원되기 때문이다. 피그마 플랜 자체는 무료로 충분하다.

Codex와 기타 클라이언트 연결

같은 MCP 설정 형식을 쓰는 클라이언트라면 동일하게 연결된다. Codex는 ~/.codex/config.toml에 [mcp_servers.figwright] 항목으로, Cursor는 MCP 설정 UI에 같은 명령을 등록한다. Hermes Agent에서는 표준 MCP 서버 등록 절차를 따른다. 이번 검증에서는 Hermes 프로젝트 디렉터리가 격리 환경에 없어 자동 설치가 스킵되었음을 확인했다.

스킬 설치(선택)

에이전트가 적절한 순간에 Figwright를 찾도록 도우미 스킬 2종을 제공한다.

npx skills add awdr74100/figwright/skills

• figma-codegen: 피그마 선택 영역을 프로젝트 스택에 맞는 코드로 변환하는 워크플로
• figma-build: 코드나 설명에서 피그마 디자인을 만드는 워크플로

설치 위치는 ~/.agents/skills/다 (Universal 스킬 경로). 스킬은 서버가 연결되어 있어야 동작한다.

112개 도구의 구성

직접 서버를 실행해 tools/list를 조회한 결과 112개 도구가 노출된다.

• 읽기: 선택 영역·문서·노드 검사, 스타일·변수·컴포넌트 조회, 폰트, 반응·모션 상태, 스크린샷, 이미지 에셋, PDF·비디오 내보내기, 다중 파일 작업
• 쓰기: 프레임·텍스트·모양 생성과 편집, 오토레이아웃, 이펙트, 스타일·변수·컴포넌트 제작, 페이지, 반응, 모션 애니메이션, 일괄 편집
• 그라운딩: get_design_context(중복 제거된 디자인 컨텍스트), component_map/token_map/icon_map(피그마 데이터와 코드베이스 조인), design_diff(기준선 대비 변경 보고)

component_map은 피그마 컴포넌트를 로컬 코드 컴포넌트에 매핑하고 재사용 가능한 것을 알려준다. 스크린샷을 보고 범용 마크업을 생성하는 방식과 달리, 기존 컴포넌트·토큰을 재활용하는 코드를 만드는 것이 그라운딩 도구의 목적이다.

기존 유명 도구와 비교: Figma 공식 MCP vs Figwright

관계는 직접 대체재다. 유료 좌석이 없거나 쓰기 기능이 필요하면 Figwright를, 공식 지원과 안정성이 우선이면 공식 서버를 선택한다.

좌석이 이미 있다면: 공식 데스크톱 서버가 지원과 문서에서 앞선다. Figwright로 갈 이유는 쓰기 도구다.

좌석이 없다면: Figwright가 유료 없이 양방향 작업을 가능하게 하는 거의 유일한 선택지다.

공식 서버와 섞어 쓰기: 서버 이름을 다르게 지정하면 공식 원격 서버(읽기)와 Figwright(쓰기)를 동시에 연결할 수도 있다.

안전한 복사·붙여넣기 설치 프롬프트

아래 프롬프트를 Claude Code나 Codex에 붙여 넣으면 된다. 운영 환경에서는 버전을 고정하고, 비밀 입력이나 기존 설정 백업 없이 진행하지 않도록 요구한다.

Figwright MCP 서버를 설치해줘. 안전하게 진행해.

1. Node.js 버전을 확인해줘. 20.19+ 또는 22.12+가 아니면 먼저 알려주고 중단해.
2. 이 프로젝트의 .mcp.json을 먼저 백업한 뒤, figwright 서버 항목을 추가해:
   command: npx, args: ["-y", "@figwright/mcp@0.5.0"]
   (@latest 대신 0.5.0으로 버전을 고정해)
3. npm 레지스트리 무결성(sha512)과 provenance attestation이 있는지 확인했다고 알려줘.
4. MCP 연결 후 tools/list에서 112개 도구와 ping이 보이는지 확인하고 결과를 보여줘.
5. 쓰기 도구(create_, set_ 계열)는 승인 없이 실행되지 않도록 클라이언트 도구 승인 설정을 켜줘.
6. 내 API 키나 비밀번호를 묻지 마. 필요하면 중단하고 이유를 설명해.
7. 완료되면 설치된 파일 경로와 제거 방법을 안내해줘.

제거는 설정 파일의 figwright 항목을 지우고, 스킬을 설치했다면 npx skills remove figma-codegen과 npx skills remove figma-build를 실행하면 끝난다. 피그마 개발 모드 플러그인은 피그마 앱에서 삭제한다. npx 캐시에만 존재하므로 전역 제거 대상은 없다.

직접 검증한 내용과 검증하지 못한 내용

직접 검증함 (2026-09-13, 격리 홈 디렉터리):

• npm 0.5.0 타르볼 sha512 무결성이 레지스트리 메타데이터와 attestation subject와 일치
• SLSA provenance가 GitHub 태그 v0.5.0과 release.yml 워크플로를 가리킴
• MCP stdio 핸드셰이크로 서버 기동, tools/list에서 112개 도구 확인
• 릴레이(127.0.0.1:3055)에 위조 Origin 요청 → 403 거부 확인
• DNS 리바인딩 형태의 비루프백 Host 헤더 → 403 거부 확인
• 번들 정적 검사: 외부 텔레메트리·분석 엔드포인트 없음, child_process는 ps 프로세스 상태 조사용 1회(인자 배열, 셸 미경유)
• npx skills add awdr74100/figwright/skills 설치 → skills.sh 보안 스캔 Safe/0 alerts/Low Risk, ~/.agents/skills/에 2개 스킬 설치 확인
• npx skills remove로 스킬 2개 제거 확인
• 실제 사용자 홈의 .claude.json, .claude/settings.json, .codex/config.toml 해시가 검증 전후 동일

검증하지 못함:

• 피그마 앱·플러그인 연동 (피그마 데스크톱 앱과 GUI가 격리 환경에 없음)
• 실제 디자인→코드, 코드→디자인 변환 품질 (양방향 실사용 미실시)
• 대규모 파일·복잡한 컴포넌트에서의 성능과 안정성
• Reddit 스레드 점수·댓글 상세 (이 서버 IP에서 Reddit이 HTML 셸만 반환)

유지보수 신호

• 2026-06-19 v0.1.0 이후 2026-08-30 v0.5.0까지 5회 릴리스 (월 1~2회)
• 최근 커밋이 2026-09-12까지 이어짐 (의존성 갱신, 그라운딩 안정화, 문서 개선)
• CHANGELOG에 기능 개선·버그 수정이 PR 단위로 상세히 기록됨
• 오픈 이슈 1개, 열린 PR 0개 (2026-09-13 기준)
• CI 워크플로 배지가 있고 npm 게시가 provenance와 함께 이루어짐

단일 개발자 프로젝트라 버스 팩터는 낮다. 장기 유지보수 관점에서는 이 점을 감안해야 한다.

유용한 경우와 추천하지 않는 경우

유용한 경우:

• 유료 좌석 없이 피그마 시안을 실제 컴포넌트 코드로 받고 싶은 프론트엔드 개발자
• 에이전트가 피그마에 화면을 직접 그리게 하고 싶은 경우 (프로토타입 자동 생성)
• 기존 코드베이스의 컴포넌트·디자인 토큰을 재활용하는 코드를 원하는 경우

추천하지 않는 경우:

• 피그마를 디자인 소스로 쓰지 않는 백엔드·인프라 개발자
• 이미 유료 Dev/Full 좌석이 있고 공식 지원이 필요한 팀
• 검증되지 않은 서드파티 로컬 서버를 허용하지 않는 보안 정책이 있는 조직
• 피그마 파일을 로컬 도구에 연결하는 것 자체가 금지된 환경

FAQ

Figwright는 무료인가?

MIT 라이선스 오픈소스고 피그마 무료 플랜에서 동작한다. 서버·스킬 모두 무료다.

공식 Figma MCP와 동시에 쓸 수 있나?

가능하다. 서버 이름을 다르게 등록하면 된다. 공식 원격 서버의 읽기와 Figwright의 쓰기를 병행하는 방식도 있다.

API 키가 필요한가?

필요 없다. 피그마 세션 자체가 인증이고, MCP 연결은 로컬 stdio다.

내 디자인 파일이 외부로 나가나?

서버·릴레이·플러그인이 모두 로컬에서 실행된다. 번들에서 외부 텔레메트리 엔드포인트를 찾지 못했다. 다만 에이전트가 대화 컨텍스트로 디자인 데이터를 모델 제공자에 보내는 것은 MCP 서버가 통제하지 않는다.

데이터 손실 위험은 없나?

쓰기 도구는 피그마 파일을 변경한다. 피그마의 버전 히스토리가 복구 수단이지만, 중요 파일은 쓰기 도구 승인을 켜고 사용하는 것이 안전하다.

스킬 설치 없이 쓸 수 있나?

가능하다. 스킬은 도구를 적절한 순간에 찾도록 돕는 라우터일 뿐, 도구 자체는 서버 연결만으로 노출된다.

관련 글: Agent Skill 설치 전 보안 검사: SkillSpector vs Snyk Agent Scan, Trail of Bits coop 설치·보안·제거 검증

공식 참고자료

• GitHub 저장소: https://github.com/awdr74100/figwright
• npm 패키지: https://www.npmjs.com/package/@figwright/mcp
• 릴리스: https://github.com/awdr74100/figwright/releases
• 보안 문서: https://github.com/awdr74100/figwright/blob/main/SECURITY.md
• Figma 공식 MCP 가이드: https://help.figma.com/hc/ko/articles/32132100833559
• MCP 보안 모범 사례: https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices

The post 피그마 유료 좌석 없이 AI 에이전트 양방향 연결: Figwright 설치·보안·제거 직접 검증 appeared first on .

AI 에이전트 추적은 일반 API 추적과 무엇이 다른가

일반 HTTP API는 요청 하나가 몇 개의 서비스 span으로 끝나는 경우가 많다. AI 에이전트는 한 요청 안에서 모델이 계획을 세우고, 여러 도구를 호출하고, 결과가 부족하면 모델을 다시 부르는 반복 구조를 가진다. 최종 응답은 성공했어도 중간 검색이 세 번 실패했거나 불필요한 모델 재호출로 비용이 커졌을 수 있다.

OpenAI Agents SDK 공식 문서는 기본 trace가 runner, task, turn, agent, generation, function tool, guardrail, handoff span을 포함한다고 설명한다. 특정 SDK를 쓰지 않더라도 이 계층은 실무 설계의 좋은 기준이 된다. 핵심은 로그 줄을 시간순으로 모으는 것이 아니라 어떤 단계가 어떤 부모 작업에서 파생됐는지 보존하는 데 있다.

먼저 정할 최소 span 구조

처음부터 모든 이벤트를 수집하면 비용과 개인정보 위험만 커진다. 아래 다섯 단계로 시작하면 대부분의 운영 질문에 답할 수 있다. 에이전트가 검색을 쓰지 않으면 retrieval span은 생략하고, 여러 도구를 병렬 실행한다면 같은 부모 아래에 형제 span으로 둔다.

W3C Trace Context의 traceparent를 서비스 경계에서 전달하면 웹 API, 작업 큐, 도구 서버가 같은 분산 trace에 참여할 수 있다. 다만 대화 전체를 하나의 무한히 긴 trace로 만들기보다 사용자 요청 단위 trace와 별도의 가명 session key를 함께 쓰는 편이 조회와 보존에 유리하다.

속성은 표준·조직·민감정보로 나눠 관리한다

OpenTelemetry 공식 사이트의 GenAI 의미 규약 페이지는 2026년 8월 현재 관련 규약이 별도 semantic-conventions-genai 저장소로 이동했다고 안내한다. 새 저장소에는 agent, inference, tool, retrieval 등 span 문서와 참조 시나리오가 있다. 아직 변할 수 있는 이름을 애플리케이션 곳곳에 직접 쓰면 업그레이드 비용이 커진다.

Langfuse 공식 OpenTelemetry 문서도 GenAI 속성 규약이 진화 중이며 수신 OTel trace를 자체 데이터 모델로 매핑한다고 밝힌다. 또한 baggage는 서비스와 외부 API 경계를 따라 전파되므로 비밀번호, API 키, 개인정보를 넣지 말라고 경고한다. 검색 필터 편의를 위해 민감값을 baggage에 넣는 설계는 피해야 한다.

Python에서 최소 추적을 붙이는 순서

다음 코드는 특정 LLM 프레임워크 자동 계측에 기대지 않고 구조를 이해하기 위한 최소 예시다. OpenTelemetry Python 공식 문서의 TracerProvider, BatchSpanProcessor, current span 구조를 따른다. app.* 속성은 이 글의 조직 예시이며 공식 GenAI 속성으로 오해하면 안 된다.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter())
)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("agent-service")

with tracer.start_as_current_span("agent.request") as root:
    root.set_attribute("app.route", "support-agent")

    with tracer.start_as_current_span("agent.model_call") as model_span:
        model_span.set_attribute("app.model", selected_model)
        result = call_model(messages)
        model_span.set_attribute("app.input_tokens", result.input_tokens)
        model_span.set_attribute("app.output_tokens", result.output_tokens)

    with tracer.start_as_current_span("agent.tool_call") as tool_span:
        tool_span.set_attribute("app.tool", "knowledge_search")
        docs = search_knowledge(result.query)

1. 개발 환경에서 console exporter로 구조를 먼저 확인한다. 부모·자식 관계가 끊기지 않는지 본다.
2. OTLP exporter를 Collector 또는 관측 백엔드에 연결한다. 애플리케이션이 각 제품의 전용 전송 코드를 직접 갖지 않게 한다.
3. 모델·도구 wrapper 한 곳에서 속성을 정규화한다. 프레임워크가 바뀌어도 대시보드 키를 유지한다.
4. 오류와 재시도를 이벤트 또는 span 상태로 남긴다. 최종 성공만 기록하면 숨은 실패 비용을 놓친다.
5. 샘플링과 보존 기간을 부하 테스트로 결정한다. trace 자체가 서비스 병목이 되지 않는지 확인한다.

운영 대시보드는 다섯 지표부터 만든다

대시보드에 모든 속성을 올리기보다 장애와 비용 결정을 직접 바꾸는 지표를 먼저 둔다. 아래 경보선은 제품 공식값이 아니라 초기 운영을 위한 예시다. 서비스의 정상 기준선을 수집한 뒤 조정해야 한다.

토큰 단가를 연결할 때는 모델과 컨텍스트 구간, 캐시 읽기·쓰기, Batch 여부에 따라 가격표가 달라질 수 있다. 따라서 span에는 계산된 비용만 남기기보다 provider, model, 입력·출력·캐시 토큰을 보존하고 비용 계산기를 별도 버전으로 관리하는 편이 감사와 재계산에 유리하다.

개인정보와 비용 때문에 실패하는 지점

• 프롬프트 원문 기본 수집: 고객 정보, 소스코드, API 키가 trace 백엔드로 복제될 수 있다. 메타데이터 우선 원칙을 적용한다.
• 모든 span 100% 장기 보존: 트래픽과 도구 호출 수가 늘면 저장·인덱싱 비용이 빠르게 커진다. 정상 요청은 head sampling, 오류·고지연은 tail sampling을 검토한다.
• 비동기 경계의 context 손실: 큐 worker와 병렬 도구 실행에서 부모 context를 전달하지 않으면 trace가 여러 조각으로 갈라진다.
• 속성의 무제한 cardinality: 원문 URL, 사용자 ID, 임의 오류 메시지를 인덱스 필드로 쓰면 조회 비용이 커진다. 정규화한 코드와 제한된 분류를 쓴다.
• 관측 백엔드 실패의 서비스 전파: exporter는 batch와 짧은 timeout을 쓰고, 추적 전송 실패 때문에 사용자 요청까지 실패하지 않게 분리한다.

OpenAI Agents SDK 문서는 추적이 기본 활성화될 수 있고, 전역 환경변수·코드·개별 실행 설정으로 끌 수 있다고 안내한다. 또한 Zero Data Retention 정책을 쓰는 조직에는 해당 trace 기능을 사용할 수 없다고 명시한다. 사용하는 SDK의 기본값과 데이터 정책을 배포 전에 반드시 확인해야 한다.

도입 단계별 체크리스트

이미 개념과 제품 선택부터 정리해야 한다면 AI 에이전트 관측성 가이드와 Langfuse·LangSmith·Phoenix·OpenTelemetry 비교를 먼저 보는 편이 낫다. 비용 분석까지 확장하려면 AI 에이전트 비용 추적 가이드를 함께 연결하면 된다.

FAQ

로그와 trace를 둘 다 남겨야 하나

둘의 역할이 다르다. trace는 요청의 단계와 부모·자식 관계, 지연을 보여주고 로그는 상세 사건과 디버그 문맥을 제공한다. 로그에 trace_id와 span_id를 넣어 상호 이동할 수 있게 만드는 구성이 실용적이다.

프롬프트와 응답을 저장하지 않으면 디버깅이 불가능하지 않나

대부분의 운영 장애는 모델명, 지연, 토큰, 도구 입력의 분류, 상태, 오류 코드만으로도 1차 진단이 가능하다. 원문이 꼭 필요한 평가 환경은 별도 동의, 마스킹, 접근 제어, 짧은 보존 기간을 적용해 분리한다.

OpenTelemetry만 설치하면 AI 비용도 자동으로 계산되나

그렇지 않다. OpenTelemetry는 신호와 context를 수집·전송하는 기반이다. 모델별 단가와 캐시·컨텍스트 구간을 반영한 비용 계산 로직 또는 이를 지원하는 백엔드가 별도로 필요하다.

trace는 요청마다 하나가 좋은가, 대화마다 하나가 좋은가

일반적으로 사용자 요청마다 trace를 만들고 가명 session 또는 thread 키로 여러 trace를 묶는 편이 낫다. 대화 전체를 하나의 장기 trace로 만들면 크기, 시간 제한, 조회가 복잡해진다.

가장 먼저 경보로 만들 지표는 무엇인가

오류율과 요청 p95 지연을 먼저 두고, 모델 호출 횟수와 요청당 토큰을 추가하는 순서가 현실적이다. 도구가 핵심인 서비스라면 도구별 오류·재시도율도 첫 단계에 포함한다.

참고 자료

• OpenTelemetry GenAI Semantic Conventions 저장소
• OpenTelemetry GenAI Agent Spans
• OpenTelemetry Python Instrumentation
• OpenAI Agents SDK Tracing
• Langfuse OpenTelemetry 문서
• W3C Trace Context

문서 확인 기준일은 2026년 8월 24일이다. OpenTelemetry GenAI 의미 규약은 진화 중이므로 실제 적용 전 저장소의 최신 상태와 사용하는 SDK·백엔드의 지원 범위를 다시 확인해야 한다.

The post AI 에이전트 추적 실무: OpenTelemetry로 지연·토큰·도구 호출 연결하기 appeared first on .

네 도구의 역할은 완전히 같지 않다

Langfuse·LangSmith·Phoenix는 trace를 저장하고 탐색하며 평가와 운영 화면을 제공하는 플랫폼이다. 반면 OpenTelemetry는 애플리케이션에서 span·metric·log를 만들고 OTLP로 보내기 위한 계측 규약과 SDK·Collector 생태계다. 따라서 “OpenTelemetry와 Langfuse 중 하나”보다 “OpenTelemetry로 계측하고 Langfuse나 Phoenix로 본다”는 조합이 더 자연스러울 수 있다.

Langfuse: 자체 호스팅과 통합 기능의 균형

Langfuse는 관측, 프롬프트 버전 관리, 평가를 같은 플랫폼에 넣는다. 공식 문서는 Python·JavaScript SDK, 다수의 프레임워크 통합, OpenTelemetry, LiteLLM 같은 게이트웨이를 통한 trace 수집을 안내한다. 세션과 사용자 단위로 비용·사용량을 묶고 에이전트 그래프와 타임라인을 보는 흐름도 갖춘다.

2026년 8월 18일 공식 가격표 기준 Langfuse Cloud Hobby는 월 5만 unit과 30일 데이터 접근을 포함한 무료 구간이다. Core는 월 29달러에 10만 unit과 90일 데이터 접근을 포함하며 초과분은 10만 unit당 8달러로 안내한다. Pro는 월 199달러와 3년 데이터 접근을 제시한다. unit 정의와 이벤트 크기에 따라 실제 비용이 달라지므로 “trace 개수”만으로 예산을 잡으면 안 된다.

자체 호스팅은 라이선스 비용을 줄일 수 있지만 무료 운영을 뜻하지 않는다. trace 본문에는 프롬프트, 검색 문서, 도구 입력·출력이 들어가므로 데이터베이스 용량, 객체 스토리지, 백업, 암호화, 버전 업그레이드 비용을 함께 계산해야 한다.

LangSmith: SaaS로 빠르게 운영 루프를 만들 때

LangSmith 공식 문서는 개별 trace 탐색뿐 아니라 대시보드, 알림, 규칙·웹훅 자동화, 온라인 평가, 사람 피드백 큐를 한 흐름으로 제공한다. LangChain 전용으로 오해하기 쉽지만 OpenAI, Anthropic, CrewAI, Vercel AI SDK, Pydantic AI 등 여러 통합을 안내한다.

현재 가격표의 Developer는 좌석당 0달러이며 월 5천 base trace 이후 사용량 과금 구조다. Plus는 좌석당 월 39달러에 월 1만 base trace를 포함한다. Enterprise에는 자체 호스팅·하이브리드 배포, SSO와 세분화된 권한 기능이 표시돼 있다. 팀이 빨리 시작하기는 쉽지만 trace·저장·좌석이 각각 어떤 단위로 늘어나는지 부하 테스트 데이터로 확인해야 한다.

데이터를 외부 SaaS로 보낼 수 없는 환경이라면 도입 속도보다 반출 정책이 우선이다. 프롬프트와 검색 결과에 개인정보나 영업 비밀이 섞일 수 있으므로 저장 전 마스킹과 payload 샘플링을 애플리케이션 계층에서 적용해야 한다.

Phoenix: OTLP 기반 로컬 분석과 평가 실험

Arize Phoenix는 OpenTelemetry 위에서 동작하며 OpenInference 계측을 사용한다. 공식 문서에 따르면 trace는 모델 호출, 검색, 도구 사용, 사용자 로직을 한 실행으로 묶는다. OTLP 수신과 함께 LlamaIndex, LangChain, DSPy, Mastra, Vercel AI SDK, OpenAI, Bedrock, Anthropic 등에 대한 자동 계측을 제공한다.

평가는 LLM 기반 평가자, 코드 기반 검사, 사람 라벨을 trace와 span에 붙이는 방식이다. Ragas·DeepEval 같은 외부 평가 도구도 연결할 수 있다. 로컬에서 RAG 검색 실패를 살피고 데이터셋 실험으로 이어가려는 팀에 특히 잘 맞는다. 다만 노트북에서 잘 보이는 것과 다중 사용자 운영은 다른 문제다. 인증, RBAC, 데이터 보존, 백업, 고가용성을 별도 체크리스트로 다뤄야 한다.

OpenTelemetry: 도구 교체 비용을 줄이는 수집 계층

OpenTelemetry의 Generative AI semantic conventions에는 에이전트 span, 모델·제공자별 span, 이벤트와 metric을 표현하는 항목이 정리돼 있다. 이 규약으로 계측하면 애플리케이션 코드가 특정 관측 제품의 데이터 모델에 깊게 묶이는 문제를 줄일 수 있다.

하지만 표준 속성을 붙였다고 운영 화면이 자동으로 생기지는 않는다. Collector의 메모리 제한, 배치 전송, 재시도, 백프레셔, 민감정보 필터, 샘플링을 설계해야 하고, 실제 저장·검색·알림을 담당할 백엔드도 필요하다. 소규모 서비스는 완성형 플랫폼으로 먼저 문제를 정의한 뒤 OTLP export를 병행하는 편이 과도한 초기 설계를 피하기 쉽다.

도입 전에 반드시 정할 데이터 스키마

도구 화면보다 먼저 “실패한 사용자 작업 하나를 어떻게 찾을 것인가”를 정해야 한다. 최상위 trace는 사용자 목표 한 건으로 잡고 모델 호출, 검색, 도구 실행, 승인 단계를 자식 span으로 둔다. 이는 기존 AI 에이전트 관측성 가이드와 AI 에이전트 비용 추적 가이드의 운영 모델을 실제 제품 선택에 연결하는 핵심이다.

1. 식별자: trace_id, session_id, user_id, team_id, project_id, environment를 넣는다.
2. 모델 호출: provider, model, input/output token, cache read/write, latency, retry를 분리한다.
3. 도구 실행: tool_name, duration, status, error_type, approval 여부를 기록한다.
4. 품질: 정답성, 근거성, 도구 선택, 정책 위반 여부를 평가 점수로 붙인다. 평가 설계는 AI Evals 실무 가이드처럼 작은 대표 질문 세트부터 시작한다.
5. 비용: 성공 실행당 비용과 실패 비용을 분리하고 가격표 버전을 보존한다.

2주 파일럿 절차

실패하기 쉬운 조건

• 모든 프롬프트와 검색 문서를 무제한 저장해 비용과 보안 위험이 함께 커진다.
• trace 이름과 속성이 팀마다 달라 대시보드 집계가 깨진다.
• 성공률만 보고 결과 품질과 사람 승인 거부율을 측정하지 않는다.
• LLM 비용만 기록하고 검색 API, 브라우저, 코드 샌드박스, 재시도 비용을 뺀다.
• 자체 호스팅을 선택하면서 백업·업그레이드·보존 정책의 운영 인건비를 0원으로 계산한다.

FAQ

LangChain을 쓰지 않아도 LangSmith를 쓸 수 있나?

쓸 수 있다. 공식 문서는 여러 모델 제공자와 에이전트 프레임워크 통합을 안내한다. 다만 현재 코드의 계측 난이도와 필요한 SDK 변경량은 파일럿에서 확인해야 한다.

OpenTelemetry만 설치하면 AI 에이전트 관측이 끝나나?

끝나지 않는다. OpenTelemetry는 수집과 전송의 표준 계층이다. trace 검색, 비용 계산, 평가, 알림, 보존을 담당할 백엔드와 운영 규칙이 별도로 필요하다.

처음에는 어떤 도구로 시작하는 편이 좋은가?

외부 SaaS 사용이 가능하면 LangSmith나 Langfuse Cloud로 2주 파일럿을 빠르게 돌리는 편이 단순하다. 데이터 반출이 어렵거나 로컬 RAG 분석이 중심이면 Langfuse 자체 호스팅이나 Phoenix를 먼저 검토한다. 어떤 선택이든 OTLP export 가능성과 데이터 내보내기 경로를 확인해야 한다.

참고 자료

• Langfuse 공식 문서
• Langfuse Cloud 공식 가격표
• LangSmith Observability 공식 문서
• LangSmith 공식 가격표
• Arize Phoenix 공식 문서
• OpenTelemetry Generative AI semantic conventions

The post AI 에이전트 관측 도구 비교: Langfuse vs LangSmith vs Phoenix vs OpenTelemetry appeared first on .

핵심 요약: 최상위 trace는 사용자 작업 1건으로 잡고, 그 아래 LLM 호출과 도구 호출을 span으로 기록한다. 모든 trace에 팀·사용자·프로젝트·환경 태그를 붙인다. 비용은 입력·출력·cache read·cache write·reasoning 토큰을 분리해 계산하고, 외부 API와 재시도 비용까지 더한다. 대시보드는 총비용보다 실행당 비용, 성공 실행당 비용, 실패 비용, 캐시 적중률을 먼저 보여줘야 한다.

요청당 비용이 아니라 실행당 총원가를 봐야 한다

일반 챗봇은 사용자 메시지 한 번과 모델 호출 한 번이 비교적 가깝다. AI 에이전트는 한 작업 안에서 계획을 만들고, 여러 모델을 호출하고, 검색·브라우저·데이터베이스·코드 실행 도구를 사용하고, 실패하면 다시 시도한다. 한 번의 사용자 요청이 10개의 LLM 호출과 20개의 도구 호출로 늘어날 수 있다.

따라서 비용의 기본 단위를 HTTP 요청이나 모델 호출로 잡으면 업무 원가를 계산하기 어렵다. 가장 실용적인 단위는 다음 세 단계다.

기존 AI 에이전트 관측성 가이드가 trace 설계와 운영 안전성을 설명했다면, 이 글은 trace에 비용 데이터를 붙여 원가와 예산을 통제하는 방법에 집중한다.

AI 에이전트 총비용 계산식

에이전트 실행 1건의 총비용은 다음 네 항목을 합쳐 계산한다.

실행 총비용 = LLM 비용 + 도구·검색 비용 + 재시도·낭비 비용 + 인프라·관측 비용

1. LLM 비용

LLM 비용도 단순히 전체 입력 토큰에 입력 단가를 곱하면 안 된다.

• 일반 입력 토큰
• cache read 입력 토큰
• cache write 또는 cache creation 토큰
• 출력 토큰
• reasoning 출력 토큰
• 이미지·오디오·영상 입력
• Batch·Priority·Long context 같은 별도 요율

제공자마다 캐시 분류와 과금 방식이 다르므로 input_tokens 하나로 합쳐 저장하면 나중에 정확한 재계산이 어렵다. 모델별 최신 단가와 캐시 차이는 2026년 하반기 LLM 비교에서 확인할 수 있다.

2. 도구·검색 비용

에이전트가 호출하는 외부 도구도 원가에 포함한다.

• 웹 검색 API와 크롤링 서비스
• 지도·번역·OCR·음성 API
• 벡터 데이터베이스 검색·저장
• 브라우저 실행과 샌드박스 컴퓨팅
• 코드 인터프리터·GPU 작업
• 문자·메일·결제·업무 SaaS API

도구가 무료 티어에 들어가더라도 호출 횟수와 사용량은 기록해야 한다. 무료 한도를 넘는 순간 비용 구조가 바뀌고, 공급자가 요금제를 변경했을 때 과거 사용량으로 영향을 계산해야 하기 때문이다.

3. 재시도와 낭비 비용

실패 후 같은 프롬프트를 다시 호출한 비용, 잘못된 도구 인자로 반복 실행한 비용, 종료 조건 없이 루프를 돈 비용은 모델 청구서에는 정상 사용량으로 표시된다. 운영 관점에서는 별도 낭비 비용이다.

다음 값을 구분한다.

• 최초 시도 비용
• 자동 재시도 비용
• 오류 복구 비용
• 사용자 취소 이후 발생한 비용
• 실패로 끝난 실행의 전체 비용
• 평가·검증 모델의 추가 비용

4. 인프라와 관측 비용

자체 호스팅 모델의 GPU 비용뿐 아니라 trace 저장소, 로그, 객체 스토리지, 데이터 웨어하우스와 대시보드 비용도 포함한다. SaaS 관측성 도구가 이벤트 수나 보존 기간에 따라 과금된다면 에이전트 실행 원가에 배부해야 한다.

월 44,000회 실행 비용 계산 예시

다음은 특정 모델 추천이 아니라 계산 구조를 설명하기 위한 가상 단가 예시다.

캐시가 없으면 실행당 LLM 비용은 $0.06, 월 $2,640이다. 입력의 절반이 cache hit라면 실행당 $0.042, 월 $1,848로 내려가 $792, 30%를 절감한다.

하지만 최종 원가는 여기서 끝나지 않는다.

완료 실행 1건당 총원가는 약 $0.054다. 모델 호출비 외 항목은 $529.84로 전체의 약 22.3%다. 모델 공급자 대시보드만 봤다면 이 비용을 제품 원가에서 놓치게 된다.

반드시 기록해야 할 비용 필드

OpenTelemetry의 GenAI semantic conventions는 2026년 7월 기준 별도 semantic-conventions-genai 저장소로 이동했으며 상태가 Development다. 속성명은 바뀔 수 있으므로 버전을 고정하고 변경 이력을 확인해야 한다.

tenant_id, team_id, 가격과 비용 필드는 조직별 custom attribute로 설계할 수 있다. OpenTelemetry 표준 속성과 자체 속성을 구분하고 접두어 규칙을 정해야 한다.

프롬프트·응답 전문을 저장하지 않아도 비용 추적은 가능하다. 개인정보와 소스코드 유출이 우려되면 본문은 마스킹하거나 저장하지 않고 토큰 수, 모델, 도구명, 상태와 비용만 남긴다.

가격표는 호출 시점에 버전으로 저장한다

비용을 조회할 때 현재 가격표를 과거 토큰에 곱하면 안 된다. 모델 가격, 캐시 할인, Long context 기준과 공급자 티어는 바뀐다. 호출 시점에 다음 정보를 함께 저장하는 편이 안전하다.

• 적용한 모델 가격표 버전과 유효일
• 요청 모델과 공급자가 반환한 실제 모델
• Standard·Batch·Priority 같은 요금 티어
• Short·Long context 구간
• cache read·cache write 단가
• 통화와 환율 기준일
• 추정 비용인지 공급자 확정 비용인지

실시간 대시보드는 추정 비용으로 빠르게 보여주고, 하루 한 번 공급자 usage·청구 데이터와 대조해 확정 비용을 보정할 수 있다. 둘 사이 차이는 반올림, 지연 집계, 공유 캐시, 무료 크레딧, 약정 할인과 공급자별 토큰 분류에서 발생한다.

팀·사용자·프로젝트별 비용 배부

배부 태그는 Gateway나 에이전트 진입점에서 강제로 붙여야 한다. 개발자가 각 모델 호출마다 직접 넣게 하면 누락이 생긴다.

권장 배부 계층

1. Tenant 또는 고객사: B2B 서비스의 고객별 원가와 마진
2. Team: 부서·개발팀별 예산
3. Project 또는 기능: 코드 리뷰, 문서 생성, 고객지원 같은 기능별 원가
4. User: 과도한 사용과 교육 필요 사용자 식별
5. Agent·Workflow·Version: 버전 변경 전후 비용 비교
6. Environment: production, staging, eval 비용 분리

예를 들어 같은 고객지원 에이전트라도 refund-agent:v3가 v2보다 성공률은 2% 높지만 실행당 비용이 40% 늘었다면 품질 개선과 원가 상승을 함께 판단할 수 있다. 총 토큰만 보면 이 의사결정이 불가능하다.

AI Gateway를 통과하도록 구성하면 모델 키, 라우팅, 공통 태그와 비용 제한을 한 지점에서 적용하기 쉽다.

도구별 역할: 하나로 모두 해결하려 하지 않는다

선택은 “가장 많은 기능”보다 통제 위치에 따라 달라진다.

• 모델 호출 전에 예산을 막아야 한다면 LiteLLM·Cloudflare 같은 Gateway 계층이 필요하다.
• 실행 원인과 품질을 분석하려면 Langfuse·LangSmith·Phoenix 같은 trace backend가 필요하다.
• 제품 종속을 줄이고 여러 backend로 보내려면 OpenTelemetry Collector를 중간에 둔다.
• 작은 팀은 Gateway 1개와 관측성 backend 1개로 시작하는 편이 운영 부담이 낮다.

비용 대시보드에 넣을 10개 패널

월간 총비용만 크게 표시한 대시보드는 원인을 알려주지 않는다. 최소한 다음 패널이 필요하다.

1. 총비용과 전일·전주 대비 증감
2. 성공 실행당 평균·P50·P95 비용
3. 실패 실행과 취소 실행의 비용
4. 팀·고객·프로젝트별 비용
5. 모델·공급자·요금 티어별 비용
6. 일반 입력·cache read·cache write·출력 토큰 비중
7. Cache hit 비율과 절감 추정액
8. 도구별 호출 수·성공률·외부 API 비용
9. 에이전트 iteration·retry 분포
10. 품질 점수 대비 비용

평균만 보면 소수의 폭주 실행을 놓칠 수 있다. P95 실행 비용, 하루 최대 실행 비용과 상위 20개 비싼 trace를 바로 열 수 있어야 한다.

예산 알림과 무한 루프 차단 기준

비용 통제는 월말 보고서보다 실행 중 제한이 중요하다.

숫자는 서비스 위험도와 마진에 맞춰 정해야 한다. 결제·배포·데이터 삭제 같은 중요한 작업을 예산 때문에 중간에 강제 종료하면 더 큰 장애가 날 수 있다. hard cap은 안전하게 재개할 수 있는 작업에 적용하고, 중요한 작업은 승인·fallback·grace budget을 둔다.

최소 비용 추적 도입 순서

1단계: 공통 식별자와 토큰 기록

사용자 작업 하나에 trace_id와 run_id를 만들고 모든 LLM·도구 호출에 전파한다. provider, request model, response model, 입력·출력·캐시 토큰을 기록한다.

2단계: 가격 계산기와 버전 추가

모델별 가격표를 코드에 흩어놓지 않고 중앙 cost map으로 관리한다. 가격 버전, 통화, 요금 티어와 estimated cost를 span에 붙인다.

3단계: 조직 배부 태그 강제

Gateway나 공통 SDK에서 tenant, team, user, project, environment, agent version을 필수화한다. 태그가 없으면 production 호출을 거부하거나 unallocated 비용으로 따로 집계한다.

4단계: 도구·재시도 비용 연결

외부 API 호출 span에 단가와 사용량을 붙인다. retry count, iteration, error type과 termination reason을 기록해 실패 비용을 분리한다.

5단계: 대시보드와 알림

총비용, 성공 실행당 비용, 실패 비용, cache hit, P95 비용과 상위 고비용 trace를 먼저 만든다. 이후 팀 예산과 실행당 상한을 적용한다.

6단계: 공급자 청구서와 대조

매일 provider usage와 내부 추정 비용을 비교한다. 차이가 일정 수준을 넘으면 가격표·모델 매핑·캐시 분류·시간대 기준을 점검한다.

운영 체크리스트

• 사용자 목표 1건을 하나의 trace로 묶었는가
• 모든 모델·도구 호출에 같은 run ID가 전파되는가
• request model과 response model을 분리했는가
• 일반 입력·cache read·cache creation·출력을 구분했는가
• reasoning·이미지·오디오 사용량을 별도로 기록하는가
• 외부 검색·브라우저·DB·GPU 비용을 포함했는가
• retry·iteration·실패 비용을 분리했는가
• 팀·사용자·프로젝트·환경 태그가 필수인가
• 가격표 버전과 요금 티어를 저장하는가
• 실시간 추정액을 공급자 청구 데이터와 대조하는가
• 프롬프트 전문 없이도 비용 분석이 가능한가
• 실행당 budget과 무한 루프 제한이 있는가

FAQ

AI 에이전트 비용 추적과 일반 LLM 비용 추적은 무엇이 다른가?

일반 LLM 비용 추적은 모델 호출별 토큰과 금액을 본다. AI 에이전트 비용 추적은 하나의 사용자 목표 아래 여러 LLM 호출, 도구 실행, 재시도, 평가와 인프라 비용을 합쳐 실행 총원가를 계산한다.

OpenTelemetry만 도입하면 비용 계산이 끝나나?

아니다. OpenTelemetry는 trace와 GenAI 속성을 표준화하지만 제품별 가격표, 조직 배부, 외부 도구 단가와 예산 차단은 별도로 구현하거나 관측성·Gateway 제품을 연결해야 한다. GenAI semantic conventions도 2026년 7월 기준 Development 상태다.

Langfuse와 LiteLLM 중 무엇을 써야 하나?

역할이 다르다. Langfuse는 trace·평가·비용 분석 backend에 가깝고 LiteLLM은 모델 Gateway와 key·user·team 예산 통제에 강하다. 비용 차단과 원인 분석이 모두 필요하면 함께 사용할 수 있다.

프롬프트와 응답을 저장해야 비용을 계산할 수 있나?

필수는 아니다. 모델, 토큰 유형별 사용량, 도구명, 상태, 재시도와 가격 버전만으로 비용을 계산할 수 있다. 민감한 프롬프트는 마스킹하거나 저장하지 않는 편이 안전하다.

캐시 적중률이 높으면 비용도 같은 비율로 줄어드나?

아니다. 캐시 할인은 캐시된 입력 부분에만 적용된다. 출력, reasoning, cache write, 도구 API와 관측 비용은 그대로 남는다. 전체 절감률은 입력 비중과 cache read 단가에 따라 달라진다.

공급자 대시보드 금액과 내부 계산이 다른 이유는 무엇인가?

시간대, 집계 지연, 반올림, 무료 크레딧, 약정 할인, 실제 응답 모델, 캐시 분류와 가격표 버전 차이 때문이다. 내부 값은 실시간 통제를 위한 추정액으로 사용하고 공급자 usage·청구 데이터로 정기 보정해야 한다.

참고 자료

• OpenTelemetry GenAI Semantic Conventions Repository — GenAI span·agent·tool·token 속성 표준
• Langfuse Token & Cost Tracking — usage 유형과 모델 가격 기반 비용 계산
• LangSmith Cost Tracking — LLM·tool·retrieval custom cost와 대시보드
• Arize Phoenix Cost Tracking — span·trace·session·project 비용 롤업
• LiteLLM Spend Tracking — key·user·team별 spend 추적
• LiteLLM Budgets and Rate Limits — 개인·팀·에이전트 예산과 실행 제한
• Cloudflare AI Gateway Analytics — 요청·토큰·캐시·오류·비용 분석

*제품 기능과 문서 상태는 2026년 7월 29일 확인 기준이며 이후 변경될 수 있다.*

The post AI 에이전트 비용 추적 가이드: 토큰·캐시·도구 호출 비용을 팀별로 관리하는 법 appeared first on .

왜 AI 에이전트에는 별도 관측성이 필요한가

전통적인 웹 서비스 관측성은 요청, 응답 시간, 오류율, CPU, 메모리, 데이터베이스 쿼리를 중심으로 설계됐다. 그러나 AI 에이전트는 여기에 새로운 실행 단계를 추가한다. 사용자의 자연어 요청을 해석하고, 모델을 호출하고, 필요한 도구를 고르고, 파일이나 API를 조작하고, 실패하면 다시 시도한다. 같은 “요청 1건” 안에 여러 번의 LLM 호출과 여러 개의 도구 실행이 들어갈 수 있다.

문제는 실패 지점이 훨씬 다양해진다는 점이다. 모델이 요구사항을 잘못 이해했을 수도 있고, 도구 인자가 틀렸을 수도 있고, 권한 승인이 거절됐을 수도 있고, API rate limit에 걸렸을 수도 있고, 테스트 실패 후 복구 전략을 잘못 선택했을 수도 있다. 단순히 “500 오류가 났다”는 로그만으로는 원인을 설명하기 어렵다.

일반 서버 로그와 AI 에이전트 관측성의 차이

반드시 추적해야 할 9가지 항목

1. 작업 목표: 사용자가 무엇을 요청했는지, 에이전트가 어떤 목표로 해석했는지 기록한다.
2. 모델명과 버전: 같은 프롬프트라도 모델과 버전에 따라 결과가 달라진다.
3. 토큰 사용량과 비용: 입력 토큰, 출력 토큰, 캐시 사용량, 모델별 단가를 추적한다.
4. 도구 호출 이력: 파일 읽기, 파일 수정, 터미널 실행, 브라우저 조작, API 호출을 span 단위로 남긴다.
5. 도구 인자와 결과: 어떤 명령이나 API 파라미터가 실행됐고 어떤 결과가 돌아왔는지 확인 가능해야 한다.
6. 사용자 승인 이력: 위험한 명령, 외부 전송, 배포, 결제성 작업은 승인 여부와 시점을 남긴다.
7. 재시도와 복구 경로: 실패 후 같은 방식을 반복했는지, 다른 전략으로 전환했는지 확인한다.
8. 최종 산출물: 생성된 PR, 파일, 문서, 배포 URL, 테스트 결과를 trace와 연결한다.
9. 민감정보 처리 상태: 프롬프트와 응답에 개인정보, API 키, 내부 문서가 포함됐는지 마스킹 여부를 남긴다.

AI 에이전트 trace는 어떻게 설계해야 하나

가장 실용적인 방식은 사용자 요청 하나를 최상위 trace로 보고, 그 아래에 LLM 호출과 도구 실행을 span으로 나누는 구조다. OpenTelemetry는 trace, metric, log를 함께 다루는 관측성 표준이며, 최근에는 Generative AI semantic conventions를 통해 모델명, 토큰 사용량, 프롬프트 관련 이벤트, 응답 관련 속성을 표현하는 방향을 제시한다.

이 구조를 쓰면 “작업이 실패했다”가 아니라 “테스트 실행 span에서 실패했고, 이후 모델이 원인을 잘못 추론해 같은 명령을 반복했다”처럼 설명할 수 있다. 운영자는 모델 품질 문제, 도구 문제, 권한 문제, 외부 API 문제를 분리해 볼 수 있다.

비용 관측성은 별도 대시보드로 봐야 한다

AI 에이전트 비용은 사용자가 체감하기 전에 급격히 늘 수 있다. 특히 장기 작업, 대용량 컨텍스트, 반복 테스트, 멀티 에이전트 작업에서는 요청 1건이 여러 모델 호출로 쪼개진다. 그래서 단순 월별 API 청구액보다 작업 단위 비용을 보는 것이 중요하다.

보안 관측성: 무엇을 남기고 무엇을 지울 것인가

AI 에이전트 관측성에서 가장 위험한 함정은 “모든 프롬프트와 응답을 그대로 저장하면 디버깅이 쉬워진다”는 생각이다. 실제 운영 환경에서는 프롬프트 안에 고객 정보, 내부 코드, API 키, 장애 로그, 사내 문서가 섞일 수 있다. 관측성은 감사 가능성을 높여야 하지만, 동시에 새로운 정보 유출 경로가 되면 안 된다.

• API 키, 토큰, 비밀번호 패턴은 저장 전에 마스킹한다.
• 원문 프롬프트 저장은 기본값이 아니라 옵션으로 둔다.
• 고위험 도구 호출은 인자 전체보다 요약과 해시를 저장하는 방식을 검토한다.
• trace 접근 권한은 개발자 전체가 아니라 운영상 필요한 인원으로 제한한다.
• 보관 기간을 정하고 오래된 원문 로그는 삭제하거나 비식별화한다.

운영 성숙도별 도입 순서

개인 AI 에이전트 서버에도 필요한 이유

개인 맥미니나 홈서버에서 OpenClaw 같은 AI 에이전트 서버를 운영할 때도 관측성은 필요하다. 개인 환경에서는 대규모 SRE 조직이 없기 때문에 오히려 기록이 더 중요하다. 언제 어떤 모델이 어떤 파일을 읽고 수정했는지, 어떤 명령이 실패했는지, 비용이 어느 작업에서 늘었는지 알 수 없으면 문제를 재현하기 어렵다.

처음부터 복잡한 대시보드를 만들 필요는 없다. 작업 ID, 모델명, 토큰, 도구 호출, 오류, 최종 산출물 링크만 JSON 로그로 남겨도 출발점으로 충분하다. 이후 필요해지면 OpenTelemetry collector, Grafana, LangSmith, 자체 대시보드 같은 도구로 확장할 수 있다.

AI 에이전트 관측성 체크리스트

• 사용자 요청 하나에 고유한 작업 ID가 붙는가
• LLM 호출마다 모델명, 입력/출력 토큰, 비용이 남는가
• 도구 호출 인자와 결과가 trace 안에 연결되는가
• 파일 수정, 터미널 실행, 외부 API 호출은 별도 span으로 남는가
• 사용자 승인 여부와 승인 시점이 기록되는가
• 프롬프트와 응답 원문 저장 정책이 정해져 있는가
• 민감정보 마스킹이 저장 전에 적용되는가
• 실패 후 재시도 횟수와 복구 전략을 볼 수 있는가
• 최종 산출물과 테스트 결과가 작업 기록에 연결되는가

FAQ

AI 에이전트 관측성이 일반 로그와 다른 점은 무엇인가?

일반 로그가 서버 요청과 오류를 남기는 데 초점을 둔다면 AI 에이전트 관측성은 LLM 호출, 프롬프트, 도구 실행, 권한 승인, 비용, 재시도, 최종 산출물을 하나의 작업 흐름으로 연결해 추적한다.

AI 에이전트 운영에서 반드시 기록해야 할 지표는 무엇인가?

최소한 모델명, 토큰 사용량, 비용, 지연 시간, 도구 호출 성공률, 재시도 횟수, 사용자 승인 이력, 오류 원인, 최종 산출물 링크를 기록해야 한다.

프롬프트와 응답을 모두 저장해도 되는가?

항상 저장하면 위험하다. 개인정보, API 키, 내부 문서, 고객 데이터가 포함될 수 있으므로 마스킹, 샘플링, 보관 기간, 접근 권한을 먼저 정해야 한다.

OpenTelemetry만 쓰면 AI 에이전트 관측성이 완성되는가?

아니다. OpenTelemetry는 공통 추적 포맷과 파이프라인을 제공하지만, 어떤 이벤트를 남기고 어떤 실패를 경보로 볼지는 서비스 정책과 평가 기준으로 별도 설계해야 한다.

개인 AI 에이전트 서버에도 관측성이 필요한가?

필요하다. 개인 서버라도 모델 비용, 파일 수정 이력, 도구 호출 실패, 장기 작업 중단 원인을 확인할 수 없으면 운영과 디버깅이 어려워진다.

참고 자료

• OpenTelemetry Observability Primer
• OpenTelemetry Generative AI Semantic Conventions
• OpenAI Agents SDK Tracing
• Anthropic Claude Code Monitoring Usage
• LangSmith Observability

The post AI 에이전트 관측성 가이드: 로그만으로는 부족한 이유 appeared first on .

갱신 이력: 2026-09-22 — OpenClaw 2026.9.5 기준으로 Node.js 요구사항(24.16+/26.1+), 기본 모델(GPT-6 Astra), 원자적 업데이트 내용을 공식 문서와 대조해 반영했다.

OpenClaw를 맥미니에 설치하면 무엇이 달라지나

OpenClaw를 맥미니에 설치하면 집이나 사무실에 항상 켜져 있는 개인 AI 에이전트 서버를 둘 수 있다. 단순한 챗봇과 달리 Gateway, 메신저 채널, skills, 모델 인증, 파일 접근 권한이 함께 움직이기 때문에 설치 직후부터 운영과 보안을 같이 설계해야 한다.

Google Trends 값은 절대 검색량이 아니라 상대 지수다. 다만 최근 12개월 흐름을 보면 AI agent는 꾸준한 큰 흐름이고, OpenClaw와 Hermes Agent에도 docs, install, skills, memory 같은 실사용 관련 관심이 붙어 있다.

OpenClaw를 한 줄로 정리하면

OpenClaw는 로컬 또는 개인 서버에서 실행되며 여러 메신저 채널을 통해 명령을 받고, 파일·터미널·브라우저·도구·skills를 연결해 작업하는 개인 AI assistant다. 공식 README 기준으로 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, Matrix, LINE, WeChat 등 여러 채널을 언급한다.

중요한 점은 Gateway가 단순 챗봇 서버가 아니라 control plane 역할을 한다는 것이다. 메시지를 받고, 어떤 agent와 tool을 사용할지 결정하고, 권한 정책과 session 상태를 관리한다. 그래서 설치 글에는 보안과 운영 항목이 반드시 들어가야 한다.

설치 전 준비물

모델 인증 방식: OAuth와 API 키 중 무엇을 쓸까

OpenClaw에서 모델을 연결하는 방식은 크게 구독 계정 기반 인증과 API 키 기반 인증으로 나눌 수 있다. 개인 사용자는 ChatGPT/Codex OAuth, GitHub Copilot device flow, Claude Code CLI 로그인처럼 이미 쓰는 구독 계정을 연결하는 방식이 편하다. 반대로 장시간 자동화, 팀 공유, 비용 통제, 서버 운영처럼 예측 가능한 과금과 권한 관리가 중요하면 API 키 방식이 더 단순하다.

OpenClaw 2026.9.5의 빠른 시작은 같은 기기에 있는 Claude Code·Codex 로그인과 API 키 후보를 찾아 실제로 검증하고 기본 모델 선택으로 이어 준다. 기본 모델을 고르지 않은 새 OpenAI 설정은 GPT-6 Astra로 시작하며, 계정에서 제공하지 않으면 설정 중 사용 가능한 모델을 고른다. 개인 실험은 이 경로가 편하지만, 장시간 자동화나 팀 공유 환경은 API 키 기반 과금과 권한 관리가 더 명확한 경우가 많다.

# 1. 개인 사용자는 OAuth/device-code 방식으로 먼저 시작
openclaw models auth login --provider openai
openclaw models auth login --provider openai --device-code

# 2. OpenRouter도 OAuth 또는 API 키 방식 선택 가능
openclaw models auth login --provider openrouter --method oauth
openclaw models auth login --provider openrouter --method api-key

# 3. 인증 후 기본 모델 선택(2026년 9월 기준 새 설정 기본값은 GPT-6 Astra)
openclaw models set openai/gpt-6-astra

OpenClaw 설치 기본 흐름

공식 설치 문서는 macOS에서 설치 스크립트를 우선 권장한다. 이 스크립트는 운영체제를 확인하고, 필요한 경우 지원되는 Node.js를 설치한 뒤 OpenClaw 설치와 온보딩을 이어 간다. 아래 첫 번째 흐름이 일반 사용자용이고, 이미 Node.js를 직접 관리할 때만 npm 대안을 쓰면 된다.

# 권장: macOS 설치 스크립트
curl -fsSL https://openclaw.ai/install.sh | bash

# 설치 확인
openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

# 대안: Node.js를 직접 관리하고 npm 12 또는 npm 11.16+를 쓸 때
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

# npm 11.15 이하에서는 --allow-scripts 옵션을 빼야 한다

공식 문서의 현재 요구사항은 Node.js 24.16+ 또는 26.1+(Node 26 권장)이다. 설치 스크립트는 Node가 없을 때 macOS에서는 Node 26을, Linux에서는 Node 24 LTS를 준비한다. npm 12 또는 11.16+는 패키지 생명주기 스크립트를 허용하기 위해 --allow-scripts=openclaw가 필요하고, npm 11.15 이하는 이 옵션 자체를 지원하지 않으므로 빼야 한다. 설치 뒤에는 openclaw doctor와 Gateway 상태, 대시보드 접속을 확인한다.

맥미니에서 먼저 잡아야 할 운영 설정

• 절전 모드와 자동 잠자기 설정을 꺼서 Gateway가 끊기지 않게 한다.
• 전용 macOS 사용자 계정을 만들고, OpenClaw가 접근할 폴더 범위를 제한한다.
• SSH 또는 화면 공유는 필요할 때만 열고, 강한 인증과 방화벽을 적용한다.
• launchd 또는 OpenClaw daemon 설치로 재부팅 후 자동 시작을 확인한다.
• OpenClaw 2026.9.5부터는 원자적 업데이트가 다음 버전을 검증한 뒤 전환한다. 상시 운영 서버는 openclaw update --channel stable로 버전을 올린다.
• 로그 위치와 에러 확인 명령을 문서화한다.
• API 키는 셸 히스토리, README, 스크립트에 남기지 않는다.

많이 함께 볼 만한 플러그인·skills·편의 도구

OpenClaw 자체 설치보다 중요한 것은 “무엇을 붙여서 실제로 편하게 쓸 것인가”다. GitHub와 ClawHub 주변 생태계를 보면 memory, skills, UI manager, VPS panel, web search MCP가 반복적으로 나타난다. 아래 항목은 모든 사용자에게 필수는 아니지만, 개인 AI 에이전트 서버를 오래 운영할 때 편의성을 크게 높이는 도구들이다.

처음 설치할 때 추천 조합

1단계: 최소 안정 조합

• OpenClaw Gateway
• 모델 인증 한 가지(API 키, OAuth, Claude CLI 로그인 중 선택)
• Telegram 또는 Discord 한 채널
• 전용 macOS 계정
• 자동 시작과 로그 확인

처음부터 모든 플러그인을 넣지 않는 것이 좋다. 먼저 Gateway와 채널 연결, 선택한 모델 인증과 기본 모델 호출, 재부팅 후 자동 시작만 검증한다. 이 상태에서 하루 정도 실제 메시지와 간단한 파일 작업을 테스트한다.

2단계: 생산성 조합

• ClawHub skills에서 자주 쓰는 작업 skill 설치
• Claude-Mem 같은 memory 계열 도구 검토
• 웹 검색 MCP 또는 공식 문서 검색 도구 추가
• 모델 failover 또는 provider fallback 설정

이 단계에서는 “매번 반복하는 작업”을 skills로 뽑아내는 것이 핵심이다. 예를 들어 블로그 리서치, 서버 상태 확인, GitHub 이슈 요약, 캘린더 브리핑처럼 자주 쓰는 일을 먼저 자동화한다.

3단계: 운영 조합

• 로그와 health check
• 비용 알림과 API 사용량 제한
• 백업과 설정 파일 버전 관리
• 원격 접근 보안 정책
• Gateway exposure runbook 확인

메신저로 컴퓨터를 조작하는 도구는 편하지만 위험하다. 공식 문서도 inbound DM을 untrusted input으로 다루라고 안내한다. 그룹 채팅이나 외부 네트워크에 열기 전에는 allowlist, pairing policy, channel별 권한을 반드시 확인해야 한다.

보안 체크리스트

설치 후 다음에 점검할 것

OpenClaw 설치가 끝나면 바로 여러 채널과 플러그인을 한꺼번에 붙이기보다 하루 정도 최소 구성으로 운영해 보는 것이 좋다. 이 기간에는 Gateway 재시작, 메신저 응답 지연, API 비용, 로그 크기, 파일 접근 범위를 확인한다. 문제가 없으면 memory, skills, 웹 검색 MCP, UI 관리 도구를 순서대로 추가한다.

FAQ

OpenClaw는 맥미니에서만 써야 하나?

아니다. OpenClaw는 macOS, Linux, Windows를 지원한다. 다만 맥미니는 저전력 상시 구동, 조용한 운영, macOS 자동화와 음성 기능 활용 측면에서 개인 AI 에이전트 서버 용도로 잘 맞는다.

OpenClaw 설치 후 가장 먼저 연결할 채널은 무엇이 좋은가?

처음에는 Telegram이나 Discord처럼 봇 토큰과 접근 제어가 비교적 명확한 채널이 좋다. 그룹 채팅에 열기 전에는 allowlist와 DM 접근 정책을 먼저 확인해야 한다.

OpenClaw에 꼭 추가할 만한 도구는 무엇인가?

모든 사람에게 필수인 도구는 없다. 다만 장기 운영에는 persistent memory 계열 도구, ClawHub skills, 웹 검색 MCP, UI 관리 도구, 비용·모델 전환 도구가 편의성을 크게 높인다.

참고 자료

• OpenClaw GitHub repository
• OpenClaw 2026.9.5 release notes
• OpenClaw Install
• OpenClaw Getting Started
• OpenClaw Onboarding CLI
• OpenClaw Gateway Security
• OpenClaw Skills
• OpenClaw OpenAI provider
• OpenClaw Anthropic provider
• OpenClaw OAuth concepts
• OpenClaw Model providers
• OpenClaw GitHub Copilot provider
• OpenClaw OpenRouter provider
• Awesome OpenClaw Skills
• Claude-Mem
• CC Switch
• AionUi
• 1Panel
• Kindly Web Search MCP Server

함께 읽으면 좋은 글

• 바이브코딩 시대 개발자의 생존 전략
• AI 코딩 에이전트 선택 기준 7가지

The post OpenClaw 설치 가이드 2026: 맥미니로 개인 AI 에이전트 서버 구축하기 appeared first on .

왜 지금 도구 레지스트리가 중요해지나

초기 AI 에이전트는 미리 등록된 몇 개의 도구만 사용했다. 웹 검색, 파일 읽기, 이메일 전송, 캘린더 수정처럼 에이전트 런타임에 이미 들어 있는 도구 목록 안에서 LLM이 하나를 고르는 구조다. 도구 수가 적을 때는 이 방식이 단순하고 효과적이다.

문제는 에이전트가 실제 업무 환경으로 들어가면서 생긴다. 회사에는 HR 시스템, 결재 API, 데이터웨어하우스, Jira, GitHub, Slack, CRM, 회계 시스템, 사내 문서 검색, 배포 파이프라인 같은 수많은 도구가 있다. 모든 도구를 에이전트 설정에 수동으로 등록하고, 모든 도구 설명을 매번 LLM 컨텍스트에 넣는 방식은 오래 버티기 어렵다.

여기서 도구 레지스트리의 필요성이 나온다. 에이전트가 처음부터 모든 도구를 들고 있는 것이 아니라, 필요한 순간에 “이 작업에 맞는 능력이 어디에 있는가”를 검색하고, 검증하고, 선택 후보로 가져오는 구조가 필요하다.

앱스토어 비유가 유용한 이유

스마트폰 앱 생태계에서 앱스토어는 단순 파일 저장소가 아니다. 사용자는 앱스토어에서 앱을 검색하고, 설명과 리뷰를 보고, 권한을 확인하고, 설치한다. 개발자는 앱을 등록하고, 버전을 관리하고, 배포 채널을 얻는다. 플랫폼은 정책, 결제, 보안, 심사, 업데이트를 관리한다.

AI 에이전트 도구 레지스트리도 비슷한 문제를 다룬다. 다만 사용자가 사람이 아니라 에이전트라는 점이 다르다. 에이전트는 앱 아이콘이나 마케팅 문구보다 기계가 읽을 수 있는 메타데이터가 필요하다. 어떤 작업에 적합한지, 호출 방식은 무엇인지, 누가 제공하는지, 신뢰할 수 있는지, 어떤 권한이 필요한지를 구조화된 형태로 받아야 한다.

Agent Registry는 무엇을 저장하나

레지스트리가 저장하거나 색인하는 것은 “코드 전체”가 아닐 수 있다. 더 중요한 것은 에이전트가 판단할 수 있는 설명과 연결 정보다. 예를 들어 어떤 MCP 서버가 있다면, 레지스트리는 그 서버가 어떤 기능을 제공하는지, 어떤 자연어 요청에 적합한지, 어떤 URL이나 엔드포인트로 연결되는지, 누가 게시했는지, 어떤 인증이 필요한지 같은 정보를 다룬다.

Google Developers Blog가 소개한 Agentic Resource Discovery, ARD는 이 문제를 표준 명세 관점에서 다룬다. ARD 공식 문서는 이를 “AI 클라이언트가 이 작업에 무엇을 사용할 수 있는가를 물으면, 발견 서비스가 맞는 리소스를 돌려주는 개방형 발견 프로토콜”로 설명한다. 또한 ARD는 호출 런타임이 아니라 호출 전 발견 계층이라고 못박는다.

Google Cloud 문서의 Agent Registry도 같은 흐름을 제품 인프라 관점에서 보여준다. 문서 목차만 봐도 agents, endpoints, MCP servers, tools, discovery, search, access control 같은 항목이 함께 등장한다. 즉, 레지스트리는 단순 목록 페이지가 아니라 에이전트와 도구를 운영하는 관리 계층으로 확장된다.

도구 레지스트리가 해결하려는 5가지 문제

1. 에이전트가 모든 도구를 미리 알 필요가 없다

현재 방식에서는 도구를 쓰려면 에이전트 설정이나 코드에 먼저 등록해야 한다. 레지스트리 방식에서는 필요한 능력을 검색해 후보를 가져올 수 있다. 이는 도구가 수십 개에서 수백 개로 늘어날 때 특히 중요하다.

2. LLM 컨텍스트에 모든 도구 설명을 넣지 않아도 된다

도구 설명이 많아질수록 컨텍스트 비용과 선택 오류가 커진다. 레지스트리는 전체 도구 목록을 매번 LLM에 주는 대신, 검색으로 소수 후보를 좁히는 역할을 할 수 있다. LLM은 모든 도구가 아니라 관련 후보 안에서 선택한다.

3. 신뢰와 출처를 기계적으로 확인할 수 있다

에이전트가 런타임에 도구를 찾는다면 피싱 도구나 잘못된 엔드포인트를 피해야 한다. 도메인 기반 카탈로그, 게시자 정보, trust metadata, 조직 정책은 “이 도구를 믿고 연결해도 되는가”라는 질문에 답하기 위한 장치다.

4. 기업 내부 도구 거버넌스가 가능해진다

기업에서는 공개 웹보다 사내 레지스트리가 먼저 중요해질 수 있다. 어떤 에이전트가 어떤 도구를 호출할 수 있는지, 민감 데이터가 외부로 나가지 않는지, 승인된 MCP 서버만 쓰는지, 감사 로그가 남는지 같은 문제가 실제 운영 병목이 되기 때문이다.

5. 도구 생태계가 플랫폼을 넘어 연결된다

한 회사의 에이전트 플랫폼 안에서만 도구를 찾는 구조는 폐쇄적이다. ARD 문서가 강조하듯, 공개 웹과 기업 내부에는 여러 발견 서비스가 존재할 수 있다. 이는 하나의 중앙 앱스토어가 아니라, 여러 레지스트리가 서로 다른 커뮤니티와 정책에 맞게 색인하는 구조에 가깝다.

MCP, A2A, ARD와의 관계

이 주제에서 가장 흔한 혼동은 레지스트리와 실행 프로토콜을 섞는 것이다. MCP는 도구를 연결하고 호출하는 방식이다. A2A는 에이전트 간 협업 방식이다. OpenAPI는 HTTP API를 설명하고 호출하는 방식이다. 반면 Agent Registry와 ARD는 그런 리소스를 “어디서 찾고 어떻게 믿을 것인가”에 초점을 둔다.

따라서 Agent Registry는 MCP의 경쟁자가 아니다. 오히려 MCP 서버가 많아질수록 “좋은 MCP 서버를 어떻게 찾고, 공식 제공자인지 어떻게 확인하고, 우리 조직 정책상 호출 가능한지 어떻게 판단할 것인가”라는 문제가 생긴다. 레지스트리는 이 질문을 다루는 계층이다.

개발자와 운영자가 지금 준비할 것

1. 도구 인벤토리를 만든다. 사내 API, MCP 서버, 자동화 스크립트, 워크플로, 데이터 조회 기능을 “에이전트가 호출 가능한 리소스” 관점으로 정리한다.
2. 사람용 문서와 기계용 메타데이터를 분리한다. 블로그 글이나 README만으로는 부족하다. 대표 질의, capability, 입력/출력, 권한, 제한사항이 구조화되어야 한다.
3. 공개 리소스와 내부 리소스를 나눈다. 공개 웹에서 발견되어도 되는 도구와 사내 에이전트만 써야 하는 도구는 레지스트리 정책이 달라야 한다.
4. 신뢰 모델을 설계한다. 도메인 소유권, 게시자 검증, 승인된 엔드포인트, 버전 고정, 감사 로그가 필요하다.
5. LLM에게 모든 도구를 주지 않는 구조를 고려한다. 검색, 후보 축소, 정책 필터링, 최종 선택의 단계를 나누면 비용과 오류를 줄일 수 있다.

앱스토어 다음은 정말 Agent Registry인가

비유로는 그렇다. 사람 중심 컴퓨팅에서 앱스토어가 앱 발견과 유통의 중심이었다면, 에이전트 중심 컴퓨팅에서는 레지스트리가 도구 발견과 거버넌스의 중심이 될 가능성이 있다. 다만 수익 배분, 리뷰, 설치 같은 소비자 앱스토어 모델이 그대로 복제된다고 보기는 어렵다.

더 현실적인 모습은 세 가지가 공존하는 구조다. 공개 웹에는 여러 오픈 레지스트리가 생기고, 클라우드 플랫폼은 관리형 Agent Registry를 제공하며, 기업 내부에는 사내 도구만 색인하는 프라이빗 레지스트리가 생긴다. 에이전트는 작업에 따라 이 중 하나 또는 여러 발견 계층을 사용한다.

이 변화가 중요한 이유는 에이전트의 능력이 모델 크기만으로 결정되지 않기 때문이다. 어떤 도구를 찾을 수 있는지, 어떤 데이터를 안전하게 조회할 수 있는지, 어떤 워크플로를 신뢰하고 실행할 수 있는지가 실제 업무 성능을 좌우한다. 모델이 두뇌라면, 레지스트리는 외부 세계와 연결되는 주소록이자 검증된 도구 상자다.

짧은 결론

AI 에이전트 도구 레지스트리는 단순한 목록 서비스가 아니다. 에이전트가 사용할 수 있는 능력을 발견하고, 설명하고, 검증하고, 정책에 맞게 연결하는 인프라다. ARD, Agent Registry, MCP 서버 검색, 사내 도구 카탈로그는 모두 같은 방향을 가리킨다. 앞으로의 질문은 “어떤 모델을 쓰는가”뿐 아니라 “그 모델이 어떤 검증된 도구 생태계에 접근할 수 있는가”가 된다.

FAQ

AI 에이전트 도구 레지스트리는 무엇인가

AI 에이전트가 사용할 수 있는 도구, 스킬, MCP 서버, API, 워크플로, 다른 에이전트를 검색하고 검증하기 위한 카탈로그 또는 검색 계층이다.

Agent Registry는 앱스토어와 같은가

비유로는 비슷하지만 완전히 같지는 않다. 앱스토어는 사람이 앱을 찾고 설치하는 유통 채널이고, Agent Registry는 에이전트가 호출 가능한 리소스를 발견하고 신뢰 정보를 확인하는 기술 계층에 가깝다.

Agent Registry가 MCP를 대체하나

대체하지 않는다. MCP는 발견된 도구를 실제로 연결하고 호출하는 방식 중 하나다. 레지스트리는 MCP 서버를 어디서 찾고 어떻게 신뢰할지 다룬다.

기업은 왜 자체 레지스트리가 필요할 수 있나

기업 내부 도구와 데이터는 권한, 감사, 정책, 보안 요구사항이 강하다. 공개 레지스트리만으로는 부족하기 때문에 사내 도구를 색인하고 승인된 에이전트만 접근하게 하는 프라이빗 레지스트리가 필요할 수 있다.

공식 출처와 같이 읽을 글

• Google Developers Blog: Announcing the Agentic Resource Discovery specification
• Agentic Resource Discovery 공식 문서
• ARD How to publish 가이드
• Google Cloud Agent Registry overview
• Agentic Resource Discovery란? AI 에이전트가 도구를 직접 찾는 검색 표준
• llms.txt 작성 방법 Best Practice
• AI 검색 최적화 GEO란?

The post AI 에이전트 도구 레지스트리 시대: 앱스토어 다음은 Agent Registry인가 appeared first on .

왜 ARD가 필요한가

지금의 AI 에이전트는 혼자 모든 일을 처리하지 않는다. 코드를 고치려면 GitHub나 CI 도구를 부르고, 회사 데이터를 보려면 내부 API를 찾고, 일정이나 문서를 처리하려면 별도 서비스에 연결한다. 문제는 에이전트가 “어떤 도구가 있는지”, “그 도구가 내가 원하는 작업에 맞는지”, “연결해도 안전한지”를 공통 방식으로 알기 어렵다는 점이다.

사람은 검색엔진, 문서, 마켓플레이스, 사내 위키를 뒤져서 도구를 고른다. 반면 에이전트는 런타임에 기계가 읽을 수 있는 설명과 신뢰 정보를 받아야 한다. ARD는 이 빈칸을 메우려는 시도다. Google의 설명처럼 에이전트 생태계가 커지려면 “필요한 능력은 어디에 있는가, 무엇을 써야 하는가, 안전하게 연결해도 되는가”라는 질문에 안정적으로 답해야 한다.

현재 도구 사용 방식과 ARD 방식의 차이

ARD를 이해할 때 가장 중요한 지점은 “LLM이 도구를 고른다”는 사실이 바뀌는 것이 아니라는 점이다. 차이는 LLM이나 에이전트가 선택할 도구 후보를 어디서 가져오느냐에 있다. 현재 방식은 미리 등록된 도구 목록 안에서 고르고, ARD 방식은 필요한 능력을 검색해 후보 도구를 동적으로 가져온다.

ARD를 한 문장으로 이해하기

ARD는 AI 에이전트가 호출할 수 있는 리소스를 웹에 게시하고, 검색하고, 검증하기 위한 표준화된 발견 계층이다. 여기서 리소스는 단순한 웹페이지가 아니라 에이전트가 실제로 사용할 수 있는 능력이다. MCP 서버, A2A 에이전트 카드, 스킬, 플러그인, API, 워크플로가 모두 후보가 된다.

중요한 점은 ARD가 실행 런타임이 아니라는 사실이다. ARD는 “무엇을 찾을지”와 “어떻게 신뢰할지”를 다룬다. 실제 호출은 MCP면 MCP 방식으로, OpenAPI면 HTTP API 방식으로, A2A면 A2A 방식으로 이루어진다.

구성 요소: 카탈로그와 레지스트리

공식 문서의 게시 가이드는 가장 단순한 시작점으로 /.well-known/ai-catalog.json 경로를 제시한다. 이 파일 안에는 호스트 정보와 리소스 목록이 들어간다. 각 리소스는 식별자, 표시 이름, 타입, URL, 기능, 설명, 대표 질의 같은 검색·매칭용 정보를 갖는다.

ai-catalog.json은 어떤 역할을 하나

ai-catalog.json은 사람이 읽는 소개 페이지가 아니라 에이전트와 레지스트리가 읽는 매니페스트다. 예를 들어 어떤 회사가 날씨 MCP 서버를 제공한다면 “이 서버는 날씨 조회와 예보 기능을 제공하고, 이런 자연어 질문에 적합하며, 이 URL에서 연결할 수 있다”는 정보를 JSON으로 공개한다.

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Dev Tools",
    "identifier": "did:web:acme.com"
  },
  "entries": [
    {
      "identifier": "urn:air:acme.com:server:weather",
      "displayName": "Acme Weather Telemetry Server",
      "type": "application/mcp-server+json",
      "url": "https://api.acme.com/mcp/weather.json",
      "capabilities": ["WeatherTool", "ForecastTool"],
      "description": "Live weather telemetry MCP server",
      "representativeQueries": [
        "what is the current wind speed in Chicago",
        "get the 5-day forecast for Seattle"
      ]
    }
  ]
}

이 예시는 공식 게시 가이드의 구조를 단순화한 것이다. 핵심은 대표 질의다. 검색엔진이 웹페이지의 제목과 본문을 색인하듯, ARD 레지스트리는 리소스 설명과 대표 질의를 이용해 “이 작업에는 어떤 능력이 맞는가”를 판단할 수 있다.

예제의 url은 최종 API endpoint가 아니다

위 예제에서 "url": "https://api.acme.com/mcp/weather.json"은 날씨 데이터를 바로 반환하는 최종 실행 API라고 보기보다, 해당 MCP 서버를 설명하는 artifact document의 위치로 보는 것이 정확하다. 에이전트나 레지스트리는 이 URL에서 weather.json을 가져와 실제 transport endpoint, tool schema, 인증 방식, 권한 범위 같은 연결 정보를 확인한다.

즉 ARD catalog entry의 url은 “이 도구를 실행하라”는 버튼이 아니라 “이 도구를 자세히 설명하는 문서를 여기서 가져가라”는 참조에 가깝다. 실제 호출은 그 문서 안에 정의된 MCP endpoint, A2A endpoint, OpenAPI servers와 paths, Skill package location 같은 정보를 따라 이루어진다.

OpenAPI 도구라면 catalog entry의 url은 보통 openapi.json을 가리키고, 실제 호출 경로는 그 문서 안의 servers와 paths에 정의된다. MCP 도구라면 url이 MCP 서버 카드나 descriptor를 가리키고, 실제 MCP 연결 endpoint는 그 descriptor 안에서 확인하는 구조가 된다.

MCP, A2A, llms.txt와 무엇이 다른가

따라서 ARD를 “MCP 다음 버전”으로 보면 헷갈린다. 더 정확한 비유는 “MCP 서버와 여러 에이전트형 리소스를 검색 가능하게 만드는 발견 표준”이다. MCP가 전원 플러그와 콘센트의 규격이라면, ARD는 “어느 방에 어떤 콘센트가 있고, 누가 관리하며, 안전한가”를 알려주는 지도에 가깝다.

이 관점은 기존에 다룬 llms.txt 작성 방법, AI 검색 최적화 GEO, AI 코딩 에이전트 선택 기준과도 이어진다. 웹이 사람을 위한 페이지 중심에서 AI가 직접 읽고 호출하는 리소스 중심으로 확장되는 흐름이다.

개발자와 사이트 운영자는 무엇을 봐야 하나

1. 내 사이트가 제공하는 능력을 목록화한다. 단순 글이 아니라 API, 계산기, MCP 서버, 워크플로, 자동화 기능처럼 에이전트가 호출할 수 있는 것을 정리한다.
2. 기계가 읽을 설명을 준비한다. 이름, 타입, URL, 기능, 대표 질의, 제한사항을 사람용 마케팅 문구가 아니라 검색·매칭용 메타데이터로 쓴다.
3. 도메인 기반 신뢰를 설계한다. 공식 도메인 아래에 카탈로그를 두면 “누가 이 리소스를 게시했는가”를 확인하기 쉬워진다.
4. 호출 프로토콜을 분리해서 생각한다. ARD는 찾는 표준이고, MCP·A2A·OpenAPI는 연결하거나 호출하는 방식이다.
5. 공개 웹과 사내망을 나눠 설계한다. 공개 검색 가능한 리소스와 사내 에이전트만 써야 하는 리소스는 서로 다른 레지스트리 정책이 필요하다.

GEO 관점에서 ARD가 중요한 이유

GEO, 즉 생성형 검색 최적화는 AI가 사이트의 내용을 이해하고 인용하거나 추천할 수 있게 만드는 작업이다. ARD는 전통적인 글 인용보다 한 단계 더 나아간다. AI가 문서를 읽는 데서 끝나는 것이 아니라, 실제 기능을 발견하고 연결할 수 있는 구조를 다루기 때문이다.

물론 ARD 파일을 둔다고 Google AI Overview나 ChatGPT에 바로 노출되는 것은 아니다. 공식 문서도 특정 레지스트리가 반드시 색인한다고 보장하지 않는다. 다만 방향성은 분명하다. 앞으로의 웹에서는 “사람이 읽는 본문”, “검색엔진이 읽는 구조화 데이터”, “LLM이 읽는 안내 파일”, “에이전트가 호출 가능한 리소스 카탈로그”가 함께 필요해질 가능성이 높다.

ARD의 현재 상태와 한계

GitHub 저장소 기준 ARD 명세는 v0.9 초안 상태다. Apache 2.0 라이선스로 공개되어 있고, AI Catalog 데이터 모델 위에 구축된다. 이는 지금 당장 모든 사이트가 필수로 도입해야 하는 완성 표준이라는 뜻이 아니다. 오히려 에이전트 생태계가 어떤 방향으로 표준화될지 보여주는 초기 신호로 보는 편이 적절하다.

또 하나의 한계는 중앙 검색엔진이 하나로 정해지는 구조가 아니라는 점이다. ARD 문서는 여러 발견 서비스가 각자 다른 리소스를 색인하고, 각자의 신뢰·랭킹·접근 정책을 적용할 수 있다고 설명한다. 공개 웹에는 여러 검색엔진이 있고, 회사 내부에는 사내 검색이 따로 있는 것과 비슷하다.

짧은 결론

ARD는 “AI 에이전트가 도구를 어떻게 호출하느냐”보다 “AI 에이전트가 쓸 만한 도구를 어떻게 찾고 믿느냐”에 초점을 둔 표준이다. MCP, A2A, OpenAPI가 에이전트 생태계의 연결 규격이라면, ARD는 그 연결 대상을 발견하는 검색·검증 계층이다. 아직 초안 단계지만 AI 검색, GEO, MCP, 에이전트 플랫폼을 다루는 개발자라면 지금부터 개념을 잡아둘 만하다.

FAQ

Agentic Resource Discovery는 무엇인가

AI 에이전트가 사용할 수 있는 도구, 스킬, MCP 서버, API, 다른 에이전트를 찾고 검증하기 위한 개방형 발견 명세다.

ARD는 MCP를 대체하나

대체하지 않는다. MCP는 호출·연결 프로토콜이고, ARD는 호출 전에 리소스를 찾고 검증하는 발견 계층이다.

ARD를 적용하려면 무엇부터 해야 하나

공개하거나 내부에서 검색 가능하게 만들 리소스를 정리하고, ai-catalog.json 매니페스트로 설명하는 것부터 시작한다. 공개 웹에서는 /.well-known/ai-catalog.json 경로가 기본 출발점이다.

ARD가 SEO 순위에 직접 영향을 주나

현재 기준으로 직접적인 SEO 순위 요소라고 볼 근거는 부족하다. 다만 AI가 사이트의 리소스와 기능을 이해하는 표준화 흐름이라는 점에서 GEO 전략과 함께 볼 가치가 있다.

공식 출처와 참고 링크

• Google Developers Blog: Announcing the Agentic Resource Discovery specification
• Agentic Resource Discovery 공식 문서
• ARD How to publish 가이드
• ards-project/ard-spec GitHub 저장소
• AI Catalog GitHub 저장소

The post Agentic Resource Discovery란? AI 에이전트가 도구를 직접 찾는 검색 표준 appeared first on .