[!IMPORTANT]
핵심 아이디어는 '더 자율적인 에이전트'가 아닙니다.
핵심 아이디어는 AI 지원 작업을 사후에 검사 가능하게 만드는 것입니다: 무엇이 실행되었는지, 무엇이 변경되었는지, 무엇이 실패했는지, 그리고 사람이 검토해야 할 곳은 어디인지입니다.

[!WARNING]
본 프로젝트는 실험적입니다. 자체적인 위협 모델(threat model), 제어 장치(controls) 및 테스트 없이는 프로덕션 보안 경계로 취급하지 마십시오.

agent-trace

PyPI

Python

License

AI 에이전트를 위한 strace.

demo

왜 (Why)

코딩 에이전트가 백그라운드 세션에서 20개의 파일을 재작성한다고 가정해 봅시다. 당신은 풀 리퀘스트(pull request)를 받습니다. 하지만 그 과정에 대한 이야기는 얻지 못합니다. 어떤 파일들을 먼저 읽었을까요? 왜 같은 도구를 세 번이나 호출했을까요? 수정 사항을 찾기 전에 무엇이 실패했나요?

대부분의 도구는 LLM 호출만 추적합니다. 그것은 한 층위(layer)에 불과합니다. 간극은 그 주변 모든 것입니다: 도구 호출, 파일 작업, 결정 지점, 오류 복구, 에이전트가 실제로 실행한 명령어들입니다. agent-strace는 전체 세션을 포착하여 나중에 다시 재생할 수 있게 해줍니다. Datadog, Honeycomb, New Relic 또는 Splunk로 내보내어 프로덕션 관측 가능성(observability)을 확보하십시오. 비용 상한선, 잘못된 파일 접촉, 너무 많은 도구 호출 등 규칙을 설정하여 에이전트를 중지시킬 수 있습니다. 에이전트는 멈춥니다. 프롬프트도, 재시도도, 손상도 없이요.

설치 (Install)

# uv 사용 (권장)
uv tool install agent-strace

...

의존성 없음(Zero dependencies). Python 3.10 이상 표준 라이브러리만 사용합니다.

여기서 시작하기: 로컬 검토 (Start here: local review)

v1 제품 방향은 집중된 로컬 증거 검토 경로입니다: 하나의 캡처 어댑터(capture adapter)를 구성하고, 세션을 기록하며, 실제로 어떤 증거가 포착되었는지 확인하고, 로컬에서 검토한 다음, 공유하거나 내보내기 전에 공개 여부를 검사합니다.

지원되는/후보/실험적 표면 분할 및 현재 릴리스 게이트는 **v1 워크플로우 문서**를 참조하십시오.
아래의 더 큰 명령어 목록은 여전히 사용 가능하지만, v1 호환성 약속에 포함된 모든 것은 아닙니다.

빠른 시작

옵션 1: CLI 후크(hooks) — 프롬프트, 응답 및 후크에서 보이는 도구 호출을 캡처합니다.

agent-strace setup             # ~/.claude/settings.json에 대한 Claude Code 후크
agent-strace setup --cli codex # ~/.codex/hooks.json에 대한 OpenAI Codex 후크
agent-strace setup --cli codex --verify # Codex 사용자 후크 + CLI 확인 (실시간 캡처 아님)
...

전체 설정 및 JSON: docs/setup.md
제공사 커버리지 및 알려진 격차: docs/capture-matrix.md

GitHub Copilot CLI 플러그인

agent-strace를 설치한 후, 추적 후크와 트레이스 분석 에이전트(trace analyst agent) 및 스킬을 활성화하기 위해 해당 저장소를 Copilot CLI 플러그인으로 설치하십시오:

copilot plugin marketplace add Siddhant-K-code/agent-trace
copilot plugin install agent-strace@agent-trace

Copilot CLI를 다시 시작한 다음, /agent를 사용하여 agent-strace:trace-analyst를 선택하십시오. 트레이스는 열려 있는 저장소의 .agent-traces/에 작성됩니다. 중복 후크가 등록되는 agent-strace setup --cli copilot을 실행하지 마십시오.

검증, 업데이트 및 사용법은 Copilot CLI 플러그인 가이드를 참조하십시오.

옵션 2: MCP 프록시 — 모든 MCP 서버를 감싸며, Cursor, Windsurf, Copilot Desktop MCP 서버와 작동합니다.

agent-strace record -- npx -y @modelcontextprotocol/server-filesystem /tmp
agent-strace replay

옵션 3: Python 데코레이터 — MCP가 필요하지 않습니다.

from agent_trace import trace_tool, start_session, end_session

start_session(name="my-agent")
...

전체 설정 가이드: docs/setup.md

할 수 있는 일

세션 이해하기

명령어	기능
`agent-strace replay <id>`	터미널에서 또는 HTML로 세션 재생(Replay)
...

제어 및 보호 (Control and protect)

명령어	기능
`agent-strace watch`	종료 스위치 규칙을 사용한 실시간 모니터링(Live monitor with kill-switch rules)
...

세션 간 분석 (Analyse across sessions)

명령어	기능
`agent-strace dashboard`	다중 세션 개요(Multi-session overview)
...

내보내기 및 통합 (Export and integrate)

명령어	기능
`agent-strace export --format otlp-genai`	Datadog, Honeycomb, Grafana, Jaeger로 내보내기(Export to)
...
전체 플래그 참조: docs/commands.md

VS Code 확장 프로그램 (VS Code extension)

확장 프로그램 패널(Extensions panel)에서 agent-strace를 설치하여 에디터를 벗어나지 않고도 실시간 세션 활동을 확인할 수 있습니다.

익명 확장 프로그램 사용 원격 측정(Anonymous extension usage telemetry)은 기본적으로 활성화되어 있으며, 명령 팔레트 또는 agentTrace.telemetry.enabled 설정에서 비활성화할 수 있습니다. 프롬프트, 추적 내용, 경로, 세션 ID, 명령어 인수 또는 리포지토리 데이터는 전송되지 않습니다.

기능	설명
상태 표시줄 (Status bar)	실시간 비용(Live cost), 도구 호출 횟수(tool call count), 활성 도구 이름. 클릭하여 이벤트 스트림을 열 수 있습니다.
...

pip install agent-strace   # 1. 설치
agent-strace setup         # 2. Claude Code에 후크 추가; 다른 CLI의 경우 --cli codex, gemini, cursor 또는 copilot 사용
# 3. VS Code에서 프로젝트 열기 — .agent-traces/가 존재할 때 확장 프로그램 활성화
...

전체 문서: docs/vscode.md

프로덕션 (Production)

OTLP 내보내기(OTLP export) — 세션은 트레이스(traces)가 되고, 도구 호출은 스팬(spans)이 됩니다:

agent-strace export <세션-id> --format otlp-genai \
  --endpoint http://localhost:4318

백엔드별 설정 (Datadog, Honeycomb, Grafana, New Relic, Splunk, Langfuse): docs/production.md

서버 측 수집기(Server-side collector) — 컨테이너, CI 및 다중 머신 환경용:

agent-strace server --port 4317 --storage ./traces
AGENT_STRACE_ENDPOINT=http://collector:4317 python my_agent.py

전체 가이드: docs/server.md

자동 계측(Auto-instrumentation) — 코드 변경 불필요:

from agent_trace.integrations import instrument_langchain
instrument_langchain()

지원 라이브러리: OpenAI Agents SDK, LangChain, LangGraph, CrewAI, LiteLLM, Anthropic SDK, OpenAI SDK, AWS Strands. 가이드: docs/integrations.md

GitHub Actions — CI에서 평가(evals) 실행 및 결과를 단계 요약에 게시하고 회귀 시 실패:

- uses: Siddhant-K-code/[email protected]
  with:
    config: .agent-evals.yaml
...

Marketplace 목록 · 액션 참조

작동 방식 (How it works)

Claude Code 훅(hooks) — Claude Code는 에이전트 루프의 모든 단계에서 훅 이벤트를 발생시킵니다. agent-strace가 핸들러로 등록되어 stdin에서 JSON을 읽고 트레이스 이벤트를 작성합니다. 각 훅은 별도의 프로세스로 실행되며, .agent-traces/.active-session의 세션 상태는 지연 시간 측정을 위해 PreToolUse와 PostToolUse를 상관관계화(correlates)합니다.

MCP stdio 프록시(proxy) — 에이전트와 MCP 서버 사이에 위치하며, JSON-RPC 메시지(Content-Length 프레임 또는 개행 구분)를 읽고 각각 분류한 다음 트레이스 이벤트를 작성합니다. 메시지는 변경 없이 전달됩니다. 에이전트와 서버는 프록시의 존재를 알지 못합니다.

MCP HTTP/SSE 프록시(proxy) — 동일한 아이디어, 다른 전송 방식입니다. 로컬 포트에서 수신 대기하며, POST 및 SSE 요청을 원격 서버로 전달하고 양방향 모든 JSON-RPC 메시지를 캡처합니다.

Python 데코레이터(decorator) — @trace_tool은 실행 전에 tool_call 이벤트를, 실행 후에 tool_result 이벤트를 기록합니다. 오류와 타이밍은 자동으로 캡처됩니다. @trace_llm_call도 LLM 호출에 대해 동일하게 작동합니다.

테스트 실행 (Running tests)

python -m unittest discover -s tests -v

라이선스 (License)

MIT. 원하는 대로 사용하세요.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

Sponsor · ADRs · Security · PyPI

agent-trace

요약

핵심 포인트

agent-trace

왜 (Why)

설치 (Install)

여기서 시작하기: 로컬 검토 (Start here: local review)

빠른 시작

GitHub Copilot CLI 플러그인

할 수 있는 일

세션 이해하기

제어 및 보호 (Control and protect)

세션 간 분석 (Analyse across sessions)

내보내기 및 통합 (Export and integrate)

VS Code 확장 프로그램 (VS Code extension)

프로덕션 (Production)

작동 방식 (How it works)

테스트 실행 (Running tests)

라이선스 (License)

댓글

agent-trace

왜 (Why)

설치 (Install)

여기서 시작하기: 로컬 검토 (Start here: local review)

빠른 시작

GitHub Copilot CLI 플러그인

할 수 있는 일

세션 이해하기

제어 및 보호 (Control and protect)

세션 간 분석 (Analyse across sessions)

내보내기 및 통합 (Export and integrate)

VS Code 확장 프로그램 (VS Code extension)

프로덕션 (Production)

작동 방식 (How it works)

테스트 실행 (Running tests)

라이선스 (License)