AI 에이전트 관측 설정 — 로그가 안 나가도 아무 말이 없습니다

직접 만든 AI 에이전트를 돌리다 보면 "얘가 지금 뭘 하고 있지"가 안 보입니다. 어떤 도구를 몇 번 불렀는지, 어디서 멈췄는지, 토큰을 얼마나 썼는지. 그래서 표준 관측 규격으로 내보내는 기능이 있는데, 공식 문서를 읽어보니 함정이 앞에 놓여 있습니다 — 내보내기가 실패해도 아무 오류가 안 뜨고, 흔히 쓰는 설정값 하나는 통신 자체를 깨뜨립니다. 붙이기 전에 알아야 할 것들만 정리했습니다.

📌 30초 요약

• ★★안 나가도 오류가 없습니다 — 조용히 버리고 계속 돕니다.
• ★화면으로 뱉게 하면 통신이 깨집니다 — 거기가 대화 통로입니다.
• ★짧은 작업은 데이터가 사라집니다 — 모아서 주기마다 보냅니다.
• ⚠️ 붙는 신원은 내 서비스지 실제 사용자가 아닙니다.
• 내 앱 추적과는 저절로 이어집니다.
• 내용은 기본 미포함 — 켜는 스위치가 넷 있습니다.

안 나가도 아무 말이 없습니다

가장 먼저 알아야 할 동작입니다. 주소를 잘못 적었거나 수집기가 안 떠 있거나 인증이 거절돼도 에이전트는 아무 일 없다는 듯 정상적으로 돕니다. 대신 모아둔 자료를 조용히 버려요. 내 프로그램 쪽에는 오류가 하나도 안 올라옵니다. 그래서 "설정은 다 했는데 화면에 아무것도 안 뜬다"로 한참 헤매기 좋습니다.

해법은 있습니다. 진단을 켜는 값을 함께 넣으면 내보내기 오류가 오류 통로로 나옵니다. 그걸 받는 방법이 언어마다 달라서 한쪽은 함수를 하나 넘기고 다른 쪽은 설정 항목으로 받습니다. 붙이자마자 이걸 먼저 켜서 한 번 제대로 도착하는지 확인하고 끄는 순서를 권합니다. 앱을 만들면서 자주 하는 실수들 중에서도 이런 조용한 실패가 가장 오래 사람을 붙잡아 둡니다.

⚠️ 화면으로 뱉게 하면 통신이 깨집니다

값을 확인하려고 "그냥 화면에 찍어라"로 설정하기 쉬운데, 문서가 이걸 딱 잘라 금지합니다. 그 출력 통로가 곧 에이전트와 내 프로그램이 대화하는 통로거든요. 관측 자료가 거기 섞이면 메시지 자체가 망가집니다. 눈으로 보고 싶으면 내 컴퓨터에 수집기를 하나 띄우고 그쪽 주소를 가리키라는 게 문서의 안내예요.

짧은 작업은 그냥 사라집니다

두 번째 함정. 자료는 모아뒀다가 정해진 주기마다 한꺼번에 나갑니다. 기본 주기가 종류별로 다른데, 숫자 세는 쪽이 가장 길고 나머지는 짧아요. 문제는 짧게 끝나는 작업이 그 주기보다 먼저 끝나버린다는 겁니다.

깨끗하게 끝나면 남은 걸 밀어내려 시도는 합니다. 다만 그 시도에도 짧은 제한 시간이 걸려 있어서, 수집기가 느리게 응답하면 그대로 버려집니다. 그리고 프로세스가 밖에서 강제로 종료되면 모아둔 것 전부가 없어져요. 처방은 단순합니다 — 주기를 짧게 줄이면 두 구멍이 다 작아집니다. 짧은 작업을 많이 돌리는 구조라면 붙이자마자 조정하세요.

내보내는 종류	담기는 것
숫자 세기	토큰·비용·세션 수·바뀐 줄 수·도구 승인 결과
사건 기록	요청마다·오류마다·도구 결과마다 한 줄씩
구간 추적	차례·모델 호출·도구·훅 — 별도 스위치가 하나 더 필요
토큰 수치	실패·중단된 요청에서는 빠질 수 있음

셋째 줄을 놓치기 쉽습니다. 구간 추적만 스위치가 하나 더 필요합니다 — 나머지 둘은 그거 없이도 나가요. 그리고 이 기능들은 SDK가 만드는 게 아닙니다. 자식으로 뜬 프로그램에 이미 계측이 들어 있어서 그쪽이 수집기로 직접 보냅니다. SDK는 설정만 전달하는 역할이에요. 그래서 통이나 관리 도구 단에 환경 값을 걸어두면 코드를 안 고쳐도 전부 적용됩니다.

내 앱 추적과 저절로 이어집니다

반가운 쪽도 있습니다. 내 프로그램에서 추적 구간이 열려 있는 상태로 에이전트를 부르면, 그 맥락이 자동으로 자식에게 넘어갑니다. 그래서 에이전트 실행이 내 앱 추적 안쪽에 자식으로 들어가요 — 따로 떠 있는 뿌리가 아니라. 사건 기록에도 같은 맥락이 실려서 구간과 기록을 이어 붙일 수 있습니다.

여기서 재미있는 게 둘 더 있습니다. 첫째, 에이전트가 실행하는 셸 명령에까지 그 맥락이 전달됩니다. 그래서 그 명령이 자기 구간을 내보내면 도구 실행 구간 아래로 자연스럽게 들어와요. 둘째, 대화형으로 쓰는 경우엔 들어오는 맥락을 아예 무시합니다 — 프로그램에서 부르는 경우에만 이어붙습니다. 곁가지 에이전트에 일을 맡기면 그쪽 구간이 부모의 도구 구간 아래로 중첩돼서 위임 사슬 전체가 한 추적에 다 보입니다. 개인 인프라를 조립해 24시간 돌리는 구성이라면, 이 연결만 잡아둬도 어디서 멎었는지 바로 짚입니다.

사용자별로 남기려면 직접 심어야 합니다

운영으로 갈 때 걸리는 대목입니다. 기록에 자동으로 붙는 신원은 앤트로픽을 부를 때 쓴 자격, 즉 내 서비스의 신원입니다. 한 배포로 여러 사용자를 받는 앱이라면 실제로 누구를 대신해 움직였는지는 안 남아요. 그래서 호출할 때마다 사용자와 소속을 속성으로 직접 심으라고 안내합니다.

여기 작은 함정 — 쉼표·공백·등호가 예약 문자라 값을 그대로 넣으면 안 됩니다. 이름에 공백이 있는 사용자 하나만 들어와도 뒤가 어긋나요. 넣기 전에 안전한 형태로 바꿔서 붙여야 합니다. 이걸 해두면 도구 승인 결과·도구 결과·서버 연결·권한 모드 변경 같은 기록이 사용자별 감사 자료가 됩니다. 여러 에이전트를 한 수집기로 보낸다면 서비스 이름도 갈아 끼우세요 — 기본값이 다 같아서 안 그러면 섞입니다.

✅ 내용은 기본적으로 안 실립니다

기본 상태에서 나가는 건 구조뿐입니다 — 걸린 시간, 모델 이름, 도구 이름 정도. 내가 시킨 말과 파일 내용은 안 나갑니다. 내용을 실으려면 스위치가 넷 있는데, 각각 시킨 말 / 도구에 넘긴 값 / 도구 입출력 전체 / 주고받은 원문 전체를 켭니다. 마지막 것이 특히 무거워요 — 대화 기록이 통째로 들어가고, 켜는 순간 앞의 셋이 드러내는 것 전부에 동의하는 셈이라고 문서가 명시합니다. 보관 승인을 받은 경로가 아니면 켜지 말라는 게 권고입니다. 에이전트를 서버에 올릴 때 이 값들을 통 단위로 걸어두는 게 가장 깔끔합니다.

자주 묻는 질문 (FAQ)

Q. 세 가지를 다 켜야 하나요?

아니요. 각각 켜는 스위치가 따로라서 필요한 것만 켜면 됩니다. 다만 전체를 켜는 값 하나는 공통으로 먼저 있어야 하고, 구간 추적만 베타 스위치가 추가로 필요합니다.

Q. 여러 번 부른 걸 한 흐름으로 보려면요?

구간마다 세션 번호가 기본으로 붙습니다. 같은 세션에 여러 번 물었다면 그 번호로 걸러서 하나의 시간축으로 볼 수 있어요. 다만 그 번호를 빼는 설정을 켜두면 안 붙습니다.

Q. 에이전트마다 설정을 다르게 줄 수 있나요?

부를 때 환경을 따로 넘기면 됩니다. 단 한쪽 언어는 넘긴 환경이 기존 것을 통째로 대체하니, 경로나 인증 열쇠까지 사라지지 않게 기존 환경을 펼쳐 넣어야 합니다. 다른 쪽은 위에 덮어쓰는 방식이라 그대로 두면 됩니다.

Q. 수집기를 따로 안 두고 비용만 보고 싶으면요?

그럴 필요 없습니다. 응답이 흘러오는 흐름에서 토큰과 비용을 바로 읽는 방법이 따로 있어요. 관측을 붙이는 건 어떤 도구가 언제 얼마나 걸렸는지까지 봐야 할 때입니다.

✨ 정리하면

관측을 붙이는 일 자체는 환경 값 몇 개면 끝납니다. 진짜 난이도는 "안 되고 있는 걸 알아채는 것"이에요. 붙이자마자 진단을 켜서 한 번 도착을 확인하고, 화면 출력은 절대 쓰지 말고, 짧은 작업이 많으면 주기를 줄이세요. 그리고 사용자별 기록이 필요하면 호출마다 직접 심어야 합니다. 비용과 권한을 함께 설계하는 흐름은 AI 지출 관리 허브에 단계별로 정리해 두었습니다.

출처: Claude Agent SDK 공식 문서 「표준 규격으로 관측하기」 (2026-08-31 열람). 구간 추적은 베타 단계로 이름과 속성이 판에 따라 바뀔 수 있으며, 세부 절차도 변경될 수 있습니다.