메인 콘텐츠로 건너뛰기
Weave for Agents는 공개 프리뷰 상태입니다. 정식 출시 전에 특성, API 및 Agents 뷰 UI가 변경될 수 있습니다.
Colab에서 사용해 보기 · GitHub 원본 Weave SDK를 사용하면 널리 사용되는 SDK나 맞춤형 하니스로 구축한 에이전트를 트레이스할 수 있습니다. 이 퀵스타트에서는 OpenTelemetry span을 생성하고 캡처할 수 있도록, 맞춤형 멀티턴 에이전트에 Weave를 수동으로 통합하는 방법을 보여줍니다. 에이전트용 Weave의 개념을 이해하려면 에이전트 트레이싱을 참조하세요. Claude Agent SDK나 Codex와 같은 SDK 또는 하니스에 Weave를 통합하려는 경우 에이전트 인테그레이션 트레이싱을 참조하세요. Weave는 빠르게 통합할 수 있도록 여러 에이전트 구축 SDK와 에이전트 하니스에 자동으로 패치됩니다.

​
학습할 내용

이 퀵스타트를 마치면 Weave와 호환되는 OTel spans를 생성하는 멀티턴 에이전트를 실제로 구현하게 됩니다. 또한 Weave가 Session, 턴, LLM Call, 도구 Call을 에이전트 코드에 어떻게 매핑하는지 이해하게 되므로, 같은 패턴을 여러분의 맞춤형 에이전트에도 적용할 수 있습니다. 이 가이드의 코드는 Wikipedia에서 정보를 찾아볼 수 있는 간단한 리서치 에이전트를 설정합니다. 이 에이전트는 세 가지 질문(세 번의 턴)을 하고, 답을 찾기 위해 언제 Wikipedia를 검색할지 LLM이 선택합니다. Weave는 모든 단계(대화, 각 질문, 각 AI 응답, 각 Wikipedia 조회)를 기록하므로 Weave Agents 뷰에서 실제로 어떤 일이 일어났는지 확인할 수 있습니다. 이 가이드에서는 다음 방법을 설명합니다.
  • weave.init()로 에이전트 트레이싱을 위해 Weave를 초기화합니다.
  • start_session / startSession 및 start_turn / startTurn으로 Session과 턴을 시작합니다.
  • start_llm / startLLM으로 LLM Call을 래핑하고 사용량을 기록합니다.
  • start_tool / startTool로 도구 실행을 래핑하고 결과를 기록합니다.
  • 결과로 생성된 Session, 턴, 도구 Call을 Agents 뷰에서 확인합니다.

​
Weave SDK가 에이전트와 함께 작동하는 방식

Weave SDK에는 에이전트를 위한 범용 OTel 수집 시스템이 포함되어 있습니다. 즉, Weave는 에이전트 코드의 모든 OTel span에서 정보를 캡처할 수 있습니다. 하지만 에이전트의 트레이스를 Weave UI의 Agents 뷰에 표시하려면, Weave가 다음 span을 별도로 처리해야 합니다.
개념PythonTypeScriptOTel span
하나의 대화weave.start_session(...)weave.startSession(...)(span 없음, 턴을 그룹화)
사용자/에이전트 간 한 번의 상호작용weave.start_turn(...)weave.startTurn(...)invoke_agent
한 번의 LLM API 호출weave.start_llm(...)weave.startLLM(...)chat
한 번의 도구 실행weave.start_tool(...)weave.startTool(...)execute_tool
Python에서는 네 함수 모두 컨텍스트 관리자(with weave.start_*(...) as obj:)로 동작합니다. 블록을 벗어날 때 예외 발생 여부와 관계없이 span을 종료하고 속성을 플러시합니다. TypeScript에서는 반환된 각 객체에 대해 .end()를 호출하세요. 예외가 발생해도 정리되도록 try { ... } finally { obj.end(); }를 사용하세요. gen_ai.usage.* 및 gen_ai.agent.name과 같은 다른 GenAI semantic-convention attributes를 지정하면 추가 정보가 표시되지만, 이는 선택 사항입니다.

​
사전 요구 사항

  • W&B 계정 및 API 키.
  • OpenAI API 키.
  • Python 3.10+ (Python 예시 실행용).
  • Node.js 18+ (TypeScript 예시 실행용, 내장 fetch가 필요합니다).

​
패키지 설치

다음 패키지를 개발 환경에 설치하세요: 
pip install weave openai requests

​
Weave 초기화

weave.init()는 W&B에 인증하고 에이전트 span을 Agents 뷰로 전송하는 OTel 익스포터를 구성합니다. 팀에 프로젝트가 아직 없으면 Weave가 처음 데이터를 기록할 때 해당 프로젝트를 생성합니다. 
import getpass
import os

os.environ["WANDB_API_KEY"] = getpass.getpass("Enter your W&B API key: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

TEAM = input("Enter your W&B team name: ")
PROJECT = input("Enter your W&B project name: ")

import weave
weave.init(f"{TEAM}/{PROJECT}")

​
도구 정의하기

다음 코드는 에이전트의 Wikipedia 검색 도구와 함께, 도구를 언제 어떻게 사용할지 지정하는 OpenAI 도구 스키마를 정의합니다. 
import json
import requests

def wikipedia_search(query: str) -> str:
    r = requests.get(
        "https://en.wikipedia.org/w/api.php",
        params={
            "action": "query", "generator": "search", "gsrsearch": query, "gsrlimit": 1,
            "prop": "extracts", "exintro": True, "explaintext": True, "format": "json",
        },
        headers={"User-Agent": "weave-demo"},
    ).json()
    return next(iter(r["query"]["pages"].values()))["extract"]

wikipedia_tool_schema = {
    "type": "function",
    "function": {
        "name": "wikipedia_search",
        "description": "Search Wikipedia for a topic and return its intro paragraph.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}

​
트레이스된 멀티턴 에이전트 실행

도구와 Weave 초기화가 준비되면, 다음 단계는 이를 완전한 에이전트 루프로 결합하는 것입니다. 이 루프는 Session, 턴, LLM Call, 도구 Call이 서로 어떻게 중첩되는지 보여줍니다. 다음 예시는 하나의 Session에서 세 개의 턴을 실행합니다. 각 턴은 다음과 같습니다.
  1. chat span을 열고 LLM이 도구를 Call할지 선택하도록 합니다.
  2. LLM이 도구를 요청하면, 해당 Call을 감싸는 execute_tool span을 열고 결과를 다시 LLM에 전달합니다.
  3. 최종 응답을 생성하기 위해 두 번째 chat span을 엽니다.
from openai import OpenAI

openai_client = OpenAI()
MODEL = "gpt-4o-mini"

def run_turn(history, user_message):
    history.append({"role": "user", "content": user_message})

    with weave.start_turn(user_message=user_message, model=MODEL):
        # LLM call 1: 모델이 도구 사용 여부를 결정할 수 있습니다.
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(
                model=MODEL, messages=history, tools=[wikipedia_tool_schema],
            )
            msg = resp.choices[0].message
            llm.output(msg.content or "")
            llm.usage = weave.Usage(
                input_tokens=resp.usage.prompt_tokens,
                output_tokens=resp.usage.completion_tokens,
            )
            history.append(msg.model_dump(exclude_none=True))

        # 도구가 요청되지 않은 경우, 첫 번째 LLM 응답이 최종 답변입니다.
        if not msg.tool_calls:
            return msg.content

        # 요청된 각 도구 Call을 실행합니다.
        for tc in msg.tool_calls:
            with weave.start_tool(
                name=tc.function.name,
                arguments=tc.function.arguments,
                tool_call_id=tc.id,
            ) as tool:
                tool.result = wikipedia_search(**json.loads(tc.function.arguments))
                history.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": tool.result,
                })

        # LLM call 2: 최종 답변을 생성합니다.
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(model=MODEL, messages=history)
            msg = resp.choices[0].message
            llm.output(msg.content)
            llm.usage = weave.Usage(
                input_tokens=resp.usage.prompt_tokens,
                output_tokens=resp.usage.completion_tokens,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

with weave.start_session(agent_name="research-bot") as session:
    history = []
    for question in [
        "Who founded Anthropic?",
        "What is Claude (the AI assistant)?",
        "Summarize what we discussed in one sentence.",
    ]:
        print(f"USER: {question}")
        print(f"AGENT: {run_turn(history, question)}\n")

​
Agents 뷰에서 에이전트 트레이스를 확인하세요

weave.init()가 실행되면 프로젝트 링크가 출력되며, 여기에서 다음을 확인할 수 있습니다.
  • Agents 탭에 research-bot용 행 1개.
  • 세 개의 턴이 포함된 Session 1개.
  • 각 턴(invoke_agent)에는 두 개의 chat span과 그 안에 중첩된 execute_tool span이 포함됨.
  • 각 chat의 token 수, 지연 시간, 모델, 전체 메시지 교환 내용.
아무 턴이나 클릭하면 입력, 출력, 도구 인수, 도구 결과를 자세히 살펴볼 수 있습니다.

​
다음 단계