하위 에이전트 트레이스

Weave의 하위 에이전트 span을 사용하여 하위 에이전트 위임을 추적하고 중첩된 에이전트 호출을 확인하세요.

이 가이드에서는 W&B Weave를 사용해 하위 에이전트를 트레이스하여, 위임된 에이전트 호출이 상위 turn과 동일한 트레이스 내에 중첩된 span으로 표시되도록 하는 방법을 설명합니다. 하위 에이전트를 트레이싱하면 부모가 어떤 전문 에이전트를 호출했는지, 각 에이전트가 무엇을 했는지, 그리고 최종 응답에 어떻게 기여했는지를 포함해 에이전트 추론의 전체 계층 구조를 확인할 수 있습니다. 이 가이드는 Weave로 멀티 에이전트 시스템을 계측하는 개발자를 위한 것입니다.

하위 에이전트는 turn 내부에서 실행되는 위임된 에이전트 호출입니다. 한 에이전트가 다른 에이전트에 작업을 넘길 때, 예를 들어 감독 에이전트가 전문 에이전트에 작업을 할당하는 경우 하위 에이전트를 사용하세요.

Weave로 이를 계측하면 하위 에이전트는 상위 turn과 동일한 트레이스 내에 중첩된 invoke_agent OpenTelemetry (OTel) span을 생성합니다. Agents 뷰에서는 이 중첩 구조가 이를 트리거한 turn 아래의 하위 에이전트 호출로 렌더링되며, 그 아래에 해당 하위 에이전트의 LLM Call과 도구 Call이 그룹화되어 표시됩니다.

​

하위 에이전트 데이터 모델

코드에 트레이싱을 계측하기 전에 Weave가 트레이스에서 하위 에이전트를 어떻게 표현하는지 이해해 두면 도움이 됩니다. weave.start_subagent span은 OTel invoke_agent span에 매핑되며, 상위 turn과 동일한 오퍼레이션 이름을 생성합니다. Weave는 트레이스의 부모-자식 관계를 통해 이 둘을 구분합니다:

Turn (invoke_agent — root span)
├── LLM call (chat)              ← 상위 에이전트의 추론
│   └── SubAgent (invoke_agent)  ← 여기서 위임 발생
│       ├── LLM call (chat)      ← 하위 에이전트의 LLM Call
│       └── 도구 Call (execute_tool)
└── LLM call (chat)              ← 상위 에이전트가 최종 답변 합성

하위 에이전트는 현재 활성 대화의 conversation_id를 상속하므로 Agents 뷰에서 나머지 대화와 함께 그룹화됩니다.

sub = weave.start_subagent(
    name="research-specialist",   # Required: identifies this sub-agent in the UI.
    model="gpt-4o",               # Optional: 비어 있으면 상위 대화의 모델을 사용합니다.
)

weave.start_subagent는 invoke_agent span을 생성하며, 이 span은 OTel 컨텍스트에서 현재 활성화된 span의 자식으로 자동 연결됩니다. 일반적으로 상위 turn 또는 위임을 트리거한 LLM Call의 자식이 됩니다. OTel 컨텍스트 전파가 이러한 부모-자식 관계를 처리하므로 명시적으로 위임을 지정할 필요는 없습니다.

​

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

다음 예시에서는 요청을 받아, 답을 찾기 위해 Wikipedia 검색 도구를 사용하는 리서치 전문 하위 에이전트에 작업을 위임하는 supervisor 에이전트를 실행합니다.

Weave는 대화를 weave.start_conversation으로 감싸고 이어서 conversation.start_turn을 사용해 전체 계층 구조를 캡처합니다. 그런 다음 Weave는 specialist의 weave.start_subagent 블록을 사용해 하위 에이전트 트레이스를 캡처하고, 각 LLM Call과 도구 실행을 하위 span으로 기록합니다.

이 예시에서는 에이전트 간 Tracing에 집중할 수 있도록 라우팅 로직을 의도적으로 생략했습니다.

import weave
from weave.conversation import Message, Usage

weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")

with weave.start_conversation(agent_name="supervisor") as conversation:
    with conversation.start_turn(user_message="Research the founders of Anthropic.") as turn:

        # 슈퍼바이저 LLM 호출: 어떤 전문가에게 위임할지 결정합니다.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.input_messages = [Message(role="user", content="Research the founders of Anthropic.")]
            llm.output("Delegating to the research specialist.")
            llm.usage = Usage(input_tokens=80, output_tokens=10)

        # 리서치 전문가에게 하위 에이전트로 위임합니다.
        with weave.start_subagent(name="research-specialist", model="gpt-4o") as sub:
            with sub.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Find founders of Anthropic.")]
                sub_llm.output("I should search for this.")
                sub_llm.usage = Usage(input_tokens=120, output_tokens=15)

                with weave.start_tool(name="wikipedia_search", arguments='{"query":"Anthropic"}') as tool:
                    tool.result = "Anthropic was founded by Dario and Daniela Amodei in 2021."

            with sub.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.output("Anthropic was founded by Dario and Daniela Amodei in 2021.")
                sub_llm.usage = Usage(input_tokens=200, output_tokens=25)

        # 슈퍼바이저 turn으로 돌아와 최종 답변을 종합합니다.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.output("Anthropic was founded by Dario and Daniela Amodei in 2021.")
            llm.usage = Usage(input_tokens=300, output_tokens=20)

Agents 뷰에서 하위 에이전트는 turn 내부에 중첩된 invoke_agent 블록으로 표시되며, 그 아래에 자체 LLM Calls와 도구 Calls가 함께 그룹화되어 나타납니다. supervisor의 직접 LLM Calls는 하위 에이전트와 같은 계층에 그대로 표시됩니다.

​

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

다음 예시에서는 콘텐츠 파이프라인 에이전트가 단일 요청을 처리할 때, 사실을 수집하는 researcher, 게시물 초안을 작성하는 writer, 최종 출력을 다듬는 reviewer의 세 하위 에이전트에 순차적으로 작업을 위임합니다.

Weave는 각 하위 에이전트마다 별도의 weave.start_subagent 블록을 열어, 세 하위 에이전트를 모두 동일한 turn 아래의 형제 관계로 캡처합니다. 각 하위 에이전트는 활성 turn의 OTel 컨텍스트를 상속하므로, 서로 아래에 중첩되는 대신 turn 아래에 중첩된 동일 레벨의 invoke_agent span으로 표시됩니다.

with weave.start_conversation(agent_name="content-pipeline") as conversation:
    with conversation.start_turn(user_message="Write a short blog post about Anthropic.") as turn:

        # Researcher 하위 에이전트: 사실 수집.
        with weave.start_subagent(name="researcher", model="gpt-4o") as researcher:
            with researcher.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Find key facts about Anthropic.")]
                sub_llm.output("I should search Wikipedia.")
                sub_llm.usage = Usage(input_tokens=80, output_tokens=15)

                with weave.start_tool(name="wikipedia_search", arguments='{"query":"Anthropic"}') as tool:
                    tool.result = "Anthropic was founded by Dario and Daniela Amodei in 2021."

        # Writer 하위 에이전트: 게시물 초안 작성.
        with weave.start_subagent(name="writer", model="gpt-4o") as writer:
            with writer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Draft a post using the research.")]
                sub_llm.output("Anthropic, founded in 2021 by Dario and Daniela Amodei, builds AI safety research...")
                sub_llm.usage = Usage(input_tokens=180, output_tokens=120)

        # Reviewer 하위 에이전트: 초안 다듬기.
        with weave.start_subagent(name="reviewer", model="gpt-4o") as reviewer:
            with reviewer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Review and tighten the draft.")]
                sub_llm.output("Final post: Anthropic, founded in 2021 by Dario and Daniela Amodei, builds AI safety research...")
                sub_llm.usage = Usage(input_tokens=200, output_tokens=140)

Agents 뷰에서는 turn에 서로 형제 관계인 세 개의 하위 에이전트 호출이 있으며, 각각 그 아래에 자체 LLM Call이 중첩되어 있고 researcher에는 도구 Call도 포함됩니다. 어느 하위 에이전트도 다른 하위 에이전트의 자식이 아닙니다.

​

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

하위 에이전트는 다시 다른 하위 에이전트에 작업을 위임할 수 있습니다. 각 start_subagent 호출은 OTel 컨텍스트에서 현재 활성 상태인 span 아래에 중첩됩니다.

with weave.start_conversation(agent_name="orchestrator") as conversation:
    with conversation.start_turn(user_message="Compare Anthropic and OpenAI.") as turn:

        with weave.start_subagent(name="research-coordinator") as coordinator:
            with weave.start_subagent(name="anthropic-researcher") as r1:
                with r1.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                    sub_llm.output("Anthropic facts...")
                    sub_llm.usage = Usage(input_tokens=120, output_tokens=30)

                # 중첩: 연구자가 자체 요약 하위 에이전트에 작업을 위임합니다.
                with weave.start_subagent(name="anthropic-summarizer") as summarizer:
                    with summarizer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                        sub_llm.output("Anthropic summary: ...")
                        sub_llm.usage = Usage(input_tokens=80, output_tokens=20)

            with weave.start_subagent(name="openai-researcher") as r2:
                with r2.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                    sub_llm.output("OpenAI facts...")
                    sub_llm.usage = Usage(input_tokens=120, output_tokens=30)

이 예시를 실행하면 turn 아래에 3단계의 중첩 구조가 생성됩니다:

turn (invoke_agent)
└── research-coordinator (invoke_agent)
    ├── anthropic-researcher (invoke_agent)
    │   ├── chat
    │   └── anthropic-summarizer (invoke_agent)   ← anthropic-researcher 내부에 중첩됨
    │       └── chat
    └── openai-researcher (invoke_agent)          ← anthropic-researcher의 형제 노드
        └── chat

Agents 뷰에서는 research-coordinator가 turn의 하위 에이전트로 표시되고, anthropic-researcher와 openai-researcher는 coordinator 아래에서 같은 수준으로 표시되며, anthropic-summarizer는 anthropic-researcher의 하위 에이전트로 표시됩니다.