Kyoko란? AI 에이전트 실행 기록으로 반복 실패를 살펴보는 법

AI 에이전트가 여러 도구를 호출하며 작업할 때 최종 답변만 보면 어디서 문제가 시작됐는지 알기 어렵습니다. 질문이 잘못 전달됐는지, 도구가 실패했는지, 이전 결과를 잘못 해석했는지 작업 과정을 나누어 살펴봐야 합니다.

Kyoko는 에이전트의 실행 기록을 분석하고 반복 실패에 대한 수정안을 만든 뒤 평가하는 과정을 지원하는 공개 프로젝트입니다. 이 글은 프로젝트 저장소의 설명을 바탕으로 구조와 한계를 살펴봅니다. 이 글을 작성하며 직접 설치하거나 성능을 재현하지는 않았습니다.

에이전트의 실행 기록은 왜 필요할까요?

여행 예약을 돕는 가상의 에이전트가 날짜가 틀린 일정을 제안했다고 해 보겠습니다. 최종 답변만 보면 단순한 오타처럼 보이지만, 실제 원인은 날짜를 잘못 읽은 입력 단계, 일정 검색 도구의 응답, 응답 해석 중 어느 곳에나 있을 수 있습니다.

실행 기록에는 설정에 따라 작업 단계, 도구 호출, 소요 시간과 오류 같은 정보가 남을 수 있습니다. 여러 실행을 비교하면 같은 유형의 실패가 반복되는 위치를 찾는 데 도움이 됩니다. 다만 기록이 많다고 원인이 자동으로 확정되지는 않습니다.

Kyoko가 설명하는 개선 흐름

공개 저장소는 다음과 같은 순환 과정을 설명합니다.

1. 실행 기록 분석: 여러 실행에서 도구 오류나 누락된 맥락 등 반복되는 문제를 찾습니다. 2. 이슈 정리: 관련 기록과 연결되는 문제를 만들고 검토합니다. 3. 수정안 제안: 수락한 문제를 바탕으로 에이전트 지침, 스킬, 평가 또는 실행 환경의 변경을 제안합니다. 4. 재평가: 실패했던 실행을 다시 시험하고 정해진 검사와 평가 결과를 비교합니다. 5. 적용 여부 결정: 설정된 정책과 검토 조건에 따라 변경을 적용하거나 보류합니다.

이 구조는 최종 답변만 고치는 것이 아니라 실패가 발생한 과정과 수정 결과를 함께 살펴보려는 시도입니다. 기존 에이전트 작업 복구 글이 작업을 이어가는 방법에 초점을 둔다면, 여기서는 여러 실행에서 반복되는 실패를 관찰하고 개선하는 과정에 초점을 둡니다.

트레이스와 OpenTelemetry는 무엇인가요?

트레이스는 하나의 요청이나 작업이 여러 단계를 거치는 흐름을 살펴보는 기록입니다. 각 단계의 기록을 스팬이라고 부르며, 시간이나 관련 속성을 담을 수 있습니다. OpenTelemetry 안내는 트레이스·메트릭·로그를 시스템의 내부 동작을 이해하는 데 쓰는 관측 신호로 설명합니다.

Kyoko 저장소는 OpenTelemetry와 관련된 연동을 지원한다고 안내합니다. 그러나 어떤 정보가 실제로 수집되는지는 에이전트의 계측과 설정에 따라 다릅니다. 프롬프트나 도구 결과에 개인정보와 비밀이 포함될 수 있으므로 수집 범위와 접근 권한을 먼저 정해야 합니다.

로컬 도구라면 외부 전송을 걱정하지 않아도 될까요?

그렇게 단정할 수 없습니다. 저장소는 기록, 이슈, 제안과 데이터베이스가 기본적으로 로컬에 보관된다고 설명하면서도, 수정안을 분석하거나 작성하는 데 Codex 또는 Claude Code 같은 외부 서비스를 사용하는 도구를 연결할 수 있다고 안내합니다. 어떤 데이터가 모델 서비스로 전달되는지는 선택한 도구와 설정에 따라 확인해야 합니다.

특히 고객 대화, API 키, 내부 코드가 포함될 수 있는 기록은 수집을 최소화하고, 필요한 경우 민감 정보를 제거한 뒤 처리하세요. 로컬 데이터베이스의 접근 권한과 보관 기간도 별도로 관리해야 합니다.

자동 수정 전에 살펴볼 한계

• 평가 범위: 준비된 테스트가 통과해도 다른 사용 사례나 기존 기능에 문제가 없다는 보장은 없습니다.
• 회귀 위험: 한 오류를 줄이는 변경이 다른 작업의 품질을 떨어뜨릴 수 있습니다.
• 기록의 품질: 누락되거나 잘못 연결된 기록으로 원인을 추정하면 수정 방향도 틀릴 수 있습니다.
• 자율성 설정: 저장소는 사람의 검토와 정책에 따른 자동 적용을 모두 설명합니다. 실제 운영에서는 영향 범위에 맞게 적용 권한을 정해야 합니다.
• 비용: 로컬 저장과 별도로 모델 호출, 재실행 및 평가에 시간과 비용이 들 수 있습니다.

원문에 있던 ‘한 번의 실행으로 정확도 24% 향상’은 적용 대상과 실험 조건을 이 글에서 확인하지 못해 일반적인 성과로 제시하지 않습니다. 자체 환경에서 같은 실패 사례와 회귀 테스트를 준비해 전후 결과를 비교하는 편이 좋습니다.

도입을 검토한다면

먼저 민감하지 않은 작은 시험 환경에서 반복되는 실패 하나를 고릅니다. 어떤 실행 기록이 수집되는지 확인한 다음 수정 전후에 같은 평가를 실행하고, 통과한 항목과 여전히 확인하지 못한 항목을 분리해 기록하세요. 자동 적용 범위를 넓히기 전에는 사람이 변경 내용과 롤백 방법을 확인하는 것이 좋습니다.

자주 묻는 질문

Kyoko가 에이전트를 완전히 자동으로 고쳐 주나요?

저장소는 검토 방식과 정책에 따른 자동 적용 방식을 설명합니다. 실제 동작은 설정과 평가 조건에 달리며, 모든 오류 해결을 보장하지 않습니다.

실행 기록이 있으면 문제 원인을 항상 알 수 있나요?

아닙니다. 기록이 부족하거나 잘못 해석될 수 있습니다. 원인 가설을 실제 재현과 테스트로 확인해야 합니다.

로컬에 저장하면 모델 비용은 없나요?

로컬 저장과 모델 사용은 별개입니다. 외부 모델이나 유료 도구를 연결하면 해당 서비스 비용이 발생할 수 있습니다.

참고 자료: Kyoko 공개 저장소, OpenTelemetry 관측성 안내. 확인일: 2026년 11월 6일.