퀵스타트: 맞춤형 에이전트 관측성 설정

Colab에서 사용해 보기 · GitHub 소스 Weave SDK를 사용하면 널리 사용되는 SDK나 맞춤형 하니스로 구축한 에이전트를 트레이스할 수 있습니다. 이 퀵스타트에서는 OpenTelemetry span을 생성하고 캡처할 수 있도록 맞춤형으로 구축한 멀티턴 에이전트에 Weave를 수동으로 통합하는 방법을 보여드립니다. 에이전트용 Weave를 개념적으로 이해하려면 에이전트 트레이싱을 참조하세요. Claude Agent SDK 또는 Codex와 같은 SDK나 하니스와 Weave를 통합하려는 경우 에이전트 인테그레이션 선택을 참조하세요. Weave는 빠르게 통합할 수 있도록 여러 에이전트 구축 SDK와 에이전트 하니스에 자동 패치됩니다.

배울 내용

이 퀵스타트를 마치면 Weave와 호환되는 OTel span을 생성하는 멀티턴 에이전트를 구현할 수 있습니다. 또한 Weave가 대화, 턴, LLM Call, 도구 Call을 에이전트 코드에 어떻게 대응시키는지도 이해하게 되므로, 동일한 패턴을 여러분의 맞춤형 에이전트에 적용할 수 있습니다. 이 가이드의 코드는 Wikipedia에서 정보를 찾아볼 수 있는 간단한 리서치 에이전트를 설정합니다. 이 에이전트는 세 가지 질문(세 개의 턴)을 하고, 답을 찾기 위해 언제 Wikipedia를 검색할지 LLM이 결정합니다. Weave는 모든 단계(대화, 각 질문, 각 AI 응답, 각 Wikipedia 조회)를 기록하므로 Weave Agents 뷰에서 어떤 일이 일어났는지 확인할 수 있습니다. 이 가이드에서는 다음 방법을 보여줍니다:

weave.init()를 사용해 에이전트 트레이싱용 Weave를 초기화합니다.
start_conversation / startConversation 및 start_turn / startTurn으로 대화와 턴을 시작합니다.
start_llm / startLLM으로 LLM Call을 래핑하고 사용량을 기록합니다.
start_tool / startTool로 도구 실행을 래핑하고 결과를 기록합니다.
토큰 수와 비용이 표시되도록 전체 토큰 사용량과 과금 가능한 모델을 기록합니다.
결과로 생성된 대화, 턴, 도구 Call을 Agents 뷰에서 확인합니다.

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

Weave SDK에는 에이전트를 위한 범용 OTel 수집 시스템이 포함되어 있으므로, Weave는 에이전트 코드의 모든 OTel span에서 정보를 캡처할 수 있습니다. 하지만 Weave UI의 Agents 뷰에서 에이전트 트레이스를 표시하려면, 다음 span은 Weave에서 특별히 처리해야 합니다.

개념	Python	TypeScript	OTel span
하나의 대화	`weave.start_conversation(...)`	`weave.startConversation(...)`	(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

npm install weave openai

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}")

// 이 프로젝트를 실행하기 전에 환경에 WANDB_API_KEY와 OPENAI_API_KEY를 설정하세요
import * as weave from 'weave';

await weave.init(`[YOUR-TEAM]/[YOUR-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"],
        },
    },
}

async function wikipediaSearch(query: string): Promise<string> {
  const url = new URL('https://en.wikipedia.org/w/api.php');
  url.search = new URLSearchParams({
    action: 'query',
    generator: 'search',
    gsrsearch: query,
    gsrlimit: '1',
    prop: 'extracts',
    exintro: 'true',
    explaintext: 'true',
    format: 'json',
  }).toString();
  const res = await fetch(url, { headers: { 'User-Agent': 'weave-demo' } });
  const data = (await res.json()) as {
    query: { pages: Record<string, { extract: string }> };
  };
  return Object.values(data.query.pages)[0].extract;
}

const wikipediaToolSchema = {
  type: 'function' as const,
  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 초기화가 준비되면, 다음 단계는 이를 완전한 에이전트 루프로 결합하는 것입니다. 이 루프는 대화, 턴, LLM Call, 도구 Call이 서로 어떻게 중첩되는지 보여줍니다. 다음 예시에서는 단일 대화에서 세 번의 턴을 실행합니다. 각 턴은 다음과 같습니다.

chat span을 열고 LLM이 도구를 Call할지 선택하게 합니다.
LLM이 도구를 요청하면 해당 Call을 execute_tool span으로 감싸고, 그 결과를 다시 LLM에 전달합니다.
두 번째 chat span을 열어 최종 답변을 생성합니다.

import weave
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 "")
            # record()는 사용량, 과금 모델, 응답 ID를 한 번의 호출로 설정합니다.
            llm.record(
                usage=weave.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            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.record(
                usage=weave.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

with weave.start_conversation(agent_name="research-bot") as conversation:
    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")

// @noErrors
import * as weave from 'weave';
import OpenAI from 'openai';

const openaiClient = new OpenAI();
const MODEL = 'gpt-4o-mini';

// history는 OpenAI 채팅 메시지의 목록입니다. 간결성을 위해 타입을 느슨하게 지정했습니다.
async function runTurn(history: any[], userMessage: string): Promise<string | null> {
  history.push({ role: 'user', content: userMessage });

  const turn = weave.startTurn({ model: MODEL });
  try {
    // LLM Call 1: 모델이 도구를 사용하기로 결정할 수 있습니다.
    const llm1 = weave.startLLM({ model: MODEL, providerName: 'openai' });
    let msg;
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
        tools: [wikipediaToolSchema],
      });
      msg = resp.choices[0].message;
      llm1.output(msg.content ?? '');
      // record()는 사용량, 과금 모델, 응답 ID를 한 번의 호출로 설정합니다.
      llm1.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push(msg);
    } finally {
      llm1.end();
    }

    // 도구가 요청되지 않은 경우, 첫 번째 LLM 응답이 최종 답변입니다.
    if (!msg.tool_calls?.length) {
      return msg.content ?? null;
    }

    // 요청된 각 도구 Call을 실행합니다.
    for (const tc of msg.tool_calls) {
      if (tc.type !== 'function') continue;
      const tool = weave.startTool({
        name: tc.function.name,
        args: tc.function.arguments,
        toolCallId: tc.id,
      });
      try {
        const { query } = JSON.parse(tc.function.arguments);
        tool.result = await wikipediaSearch(query);
        history.push({ role: 'tool', tool_call_id: tc.id, content: tool.result });
      } finally {
        tool.end();
      }
    }

    // LLM Call 2: 최종 답변을 종합합니다.
    const llm2 = weave.startLLM({ model: MODEL, providerName: 'openai' });
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
      });
      const msg2 = resp.choices[0].message;
      llm2.output(msg2.content ?? '');
      llm2.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push({ role: 'assistant', content: msg2.content });
      return msg2.content ?? null;
    } finally {
      llm2.end();
    }
  } finally {
    turn.end();
  }
}

const conversation = weave.startConversation({ agentName: 'research-bot' });
try {
  const history: any[] = [];
  for (const question of [
    'Who founded Anthropic?',
    'What is Claude (the AI assistant)?',
    'Summarize what we discussed in one sentence.',
  ]) {
    console.log(`USER: ${question}`);
    console.log(`AGENT: ${await runTurn(history, question)}\n`);
  }
} finally {
  conversation.end();
}

토큰 사용량 및 비용 기록

각 chat span에는 토큰 사용량과 모델 ID가 포함됩니다. Weave는 사용량을 바탕으로 토큰 수를 표시하고, 사용량과 모델 ID를 바탕으로 비용을 계산합니다. 따라서 값이 불완전하거나 가격을 계산할 수 없으면 나머지 트레이스가 올바르게 보여도 0 in / 0 out 토큰 또는 Cost -로 표시됩니다. record(...)를 사용하면 이러한 필드(output_messages, response_id, reasoning 등 포함)를 한 번에 설정할 수 있습니다. 전달한 필드만 적용됩니다. 비용이 표시되려면 다음 두 가지가 모두 정확해야 합니다.

완전한 사용량. input_tokens는 캐시된 토큰을 포함한 전체 입력입니다. Weave는 캐시 읽기와 캐시 쓰기에 각각 별도의 요율을 적용하고 이를 입력 총계에서 차감하므로, cache_read_input_tokens와 cache_creation_input_tokens는 이를 포함한 전체 input_tokens와 함께 보고해야 합니다. 프롬프트 캐싱을 지원하는 공급자(예: Anthropic)의 경우 캐시된 토큰이 입력의 대부분을 차지하는 일이 흔하므로, 이를 누락하면 사용량과 비용이 거의 0으로 표시됩니다.
가격 계산이 가능한 모델 ID. 비용은 모델을 조회해 계산됩니다. Weave는 response_model(공급자가 실제로 서빙한 정확한 모델)을 우선 사용하고, 없으면 start_llm에 전달한 model을 사용합니다. opus나 sonnet 같은 별칭은 가격 계산이 불가능하므로 Cost -로 표시됩니다. 따라서 응답이 반환한 구체적인 ID(resp.model)를 response_model로 전달하세요.

OpenAI는 캐시된 토큰을 prompt_tokens에 포함해 계산하므로 위 예시는 그대로 매핑됩니다. Anthropic은 캐시된 토큰을 input_tokens와 별도로 보고하므로, Weave가 가격을 계산하는 총계에 다시 더해야 합니다.

with weave.start_llm(model=MODEL, provider_name="anthropic") as llm:
    resp = anthropic_client.messages.create(
        model=MODEL, max_tokens=1024, messages=history,
    )
    u = resp.usage
    llm.output(resp.content[0].text)
    llm.record(
        usage=weave.Usage(
            input_tokens=u.input_tokens
            + u.cache_read_input_tokens
            + u.cache_creation_input_tokens,
            output_tokens=u.output_tokens,
            cache_read_input_tokens=u.cache_read_input_tokens,
            cache_creation_input_tokens=u.cache_creation_input_tokens,
        ),
        response_id=resp.id,
        response_model=resp.model,
    )

const u = resp.usage;
llm.record({
  usage: {
    inputTokens:
      u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens,
    outputTokens: u.output_tokens,
    cacheReadInputTokens: u.cache_read_input_tokens,
    cacheCreationInputTokens: u.cache_creation_input_tokens,
  },
  responseId: resp.id,
  responseModel: resp.model,
});

Agents 뷰에서 에이전트 트레이스 확인하기

weave.init()가 실행되면 다음을 확인할 수 있는 프로젝트 링크가 출력됩니다.

Agents 탭에 research-bot에 대한 행 하나
세 개의 턴이 포함된 대화 하나
각 턴(invoke_agent) 안에 중첩된 chat span 두 개와 execute_tool span 하나
각 chat의 토큰 수, 지연 시간, 모델, 그리고 전체 메시지 교환 내용

아무 턴이나 클릭하여 입력, 출력, 도구 인수, 도구 결과를 확인하세요.

앱에서 대화로 연결하기

자체 UI에서 Weave Agents 뷰의 대화로 딥링크하려면 entity, 프로젝트, 대화 id를 사용해 URL을 구축하세요. weave.init()는 entity와 project를 포함하는 클라이언트를 반환하고, start_conversation은 conversation_id를 제공합니다.

from weave.trace.urls import agent_conversation_path

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

with weave.start_conversation(agent_name="research-bot") as conversation:
    # ... 턴 실행 ...
    url = agent_conversation_path(
        client.entity, client.project, conversation.conversation_id
    )
    print(f"View this conversation at {url}")

이 기능은 TypeScript에서 사용할 수 없습니다.

다음 단계

Weave로 에이전트 트레이싱하는 방법과 Weave SDK에서 사용할 수 있는 특성 및 옵션을 알아보세요.
에이전트에 Weave를 통합하는 추가 옵션은 에이전트 인테그레이션 선택을 참조하세요.

시작하기

가이드

쿡북

레퍼런스

세부 정보 및 지원

퀵스타트: 맞춤형 에이전트 관측성 설정

배울 내용

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

사전 요구 사항

패키지 설치

Weave 초기화

도구 정의하기

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

토큰 사용량 및 비용 기록

Agents 뷰에서 에이전트 트레이스 확인하기

앱에서 대화로 연결하기

다음 단계

​배울 내용

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

​사전 요구 사항

​패키지 설치

​Weave 초기화

​도구 정의하기

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

​토큰 사용량 및 비용 기록

​Agents 뷰에서 에이전트 트레이스 확인하기

​앱에서 대화로 연결하기

​다음 단계

배울 내용

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

사전 요구 사항

패키지 설치

Weave 초기화

도구 정의하기

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

토큰 사용량 및 비용 기록

Agents 뷰에서 에이전트 트레이스 확인하기

앱에서 대화로 연결하기

다음 단계