Skip to main content
이 가이드에서는 CoreWeave Agent Lens로 하위 에이전트를 트레이스하여, 위임된 에이전트 호출이 상위 턴과 같은 트레이스 안에 중첩된 span으로 표시되도록 하는 방법을 설명합니다. 하위 에이전트를 트레이싱하면 상위 에이전트가 어떤 전문 에이전트를 호출했는지, 그 에이전트가 무엇을 했는지, 최종 답변에 어떻게 기여했는지 등 에이전트 추론의 전체 계층 구조를 파악할 수 있습니다. 이 가이드는 Agent Lens로 멀티 에이전트 시스템을 계측하는 개발자를 대상으로 합니다. 하위 에이전트는 턴 안에서 실행되는 위임된 에이전트 호출입니다. 감독자 에이전트가 전문 에이전트에게 작업을 배분하는 경우처럼 한 에이전트가 다른 에이전트에게 작업을 넘길 때 하위 에이전트를 사용하세요. Agent Lens로 계측한 하위 에이전트는 상위 턴과 같은 트레이스 안에 중첩된 invoke_agent OpenTelemetry(OTel) span을 생성합니다. Conversations 탭에서는 이 중첩 구조가 해당 하위 에이전트를 트리거한 턴 아래에 하위 에이전트 호출로 표시되며, 그 아래에 하위 에이전트의 LLM Call과 도구 Call이 그룹화되어 나타납니다.

하위 에이전트 데이터 모델

코드를 계측하기 전에 Agent Lens가 트레이스에서 하위 에이전트를 어떻게 표현하는지 알아 두면 도움이 됩니다. tracing.start_subagent span은 OTel invoke_agent span에 매핑되며, 상위 턴과 동일한 오퍼레이션 이름을 내보냅니다. Agent Lens는 트레이스 내 부모-자식 관계를 기준으로 두 span을 구분합니다.
하위 에이전트는 활성 대화의 conversation_id를 상속하므로, Conversations 탭에서 해당 대화의 다른 항목과 함께 그룹화됩니다.
tracing.start_subagent는 invoke_agent span을 생성하며, 이 span은 OTel 컨텍스트에서 현재 활성 상태인 span의 하위 span이 자동으로 됩니다. 이 활성 span은 일반적으로 상위 턴이거나 위임을 트리거한 LLM Call입니다. 부모-자식 관계는 OTel 컨텍스트 전파로 처리되므로 위임을 명시적으로 지정할 필요가 없습니다.

단일 하위 에이전트 트레이싱하기

다음 예시에서는 감독자 에이전트가 요청을 받아 연구 전문 하위 에이전트에게 위임하고, 이 하위 에이전트는 Wikipedia 검색 도구를 사용해 답을 찾습니다. Agent Lens는 대화를 tracing.start_conversation으로 감싸고 그 안을 다시 conversation.start_turn으로 감싸 전체 계층 구조를 캡처합니다. 그런 다음 전문 에이전트용 tracing.start_subagent 블록으로 하위 에이전트 트레이스를 캡처하고, 각 LLM Call과 도구 실행을 하위 span으로 기록합니다. 이 예시에서는 에이전트 간 트레이싱에 집중할 수 있도록 라우팅 로직을 의도적으로 생략했습니다.
Conversations 탭에서 하위 에이전트는 턴 내부에 중첩된 invoke_agent 블록으로 표시되며, 하위 에이전트의 LLM Call과 도구 Call은 그 아래에 그룹화됩니다. 슈퍼바이저가 직접 수행한 LLM Call은 하위 에이전트와 같은 수준의 형제 항목으로 남습니다.

여러 하위 에이전트 트레이스하기

다음 예시에서는 콘텐츠 파이프라인 에이전트를 실행합니다. 이 에이전트는 하나의 요청을 처리할 때 형제 관계인 세 하위 에이전트에 작업을 순서대로 위임합니다. 사실 정보를 수집하는 researcher, 게시물 초안을 작성하는 writer, 최종 출력을 다듬는 reviewer입니다. Agent Lens는 하위 에이전트마다 별도의 tracing.start_subagent 블록을 열어 세 하위 에이전트를 모두 같은 턴 아래의 형제로 캡처합니다. 각 하위 에이전트가 활성 턴의 OTel 컨텍스트를 상속하므로, 하위 에이전트끼리 서로 중첩되지 않고 턴 아래에 중첩된 동등한 invoke_agent span으로 표시됩니다.
Conversations 탭을 보면 턴에 형제 관계인 하위 에이전트 호출 세 개가 있고, 각 호출 아래에는 해당 호출의 LLM Call이 중첩되어 있으며, researcher에는 도구 Call도 포함되어 있습니다. 하위 에이전트는 서로 부모-자식 관계가 아닙니다.

중첩된 하위 에이전트 트레이스하기

하위 에이전트는 또 다른 하위 에이전트에게 작업을 위임할 수 있습니다. 각 start_subagent 호출은 OTel 컨텍스트에서 현재 활성 상태인 span의 하위에 중첩됩니다.
이 예시를 실행하면 턴 아래에 3단계 중첩 구조가 생성됩니다.
Conversations 탭에서 research-coordinator는 턴의 하위 에이전트로 표시되고, anthropic-researcher와 openai-researcher는 코디네이터 아래에 형제 항목으로 표시되며, anthropic-summarizer는 anthropic-researcher의 하위 에이전트로 표시됩니다.
마지막 수정일 2026년 9월 30일