메인 콘텐츠로 건너뛰기
OpenTelemetry (OTEL)를 사용해 Weave에서 PydanticAI 에이전트 및 도구 call을 트레이스할 수 있습니다. PydanticAI는 Pydantic 팀이 생성형 AI로 프로덕션 수준의 애플리케이션을 간단하고 타입 안전하게 구축할 수 있도록 만든 Python 에이전트 프레임워크입니다. 모든 에이전트 및 도구 call을 트레이싱하기 위해 OTEL을 사용합니다.
Weave의 OTEL 트레이싱에 관한 자세한 내용은 Send OTEL Traces to Weave를 참조하세요.
이 가이드는 Weave에서 에이전트 및 도구 실행에 대한 가시성이 필요한 PydanticAI 에이전트를 구축하는 개발자를 위한 것입니다. 이 가이드에서는 OTEL을 사용해 PydanticAI 에이전트 및 도구 call을 트레이스하고, Weave에서 해당 트레이스를 시각화하는 방법을 보여줍니다. 필요한 의존성을 설치하고, Weave로 데이터를 전송하도록 OTEL tracer를 설정하고, PydanticAI 에이전트와 도구를 계측하는 방법을 알아봅니다. 또한 애플리케이션의 모든 에이전트에서 기본적으로 트레이싱을 활성화하는 방법도 살펴봅니다.

사전 요구 사항

트레이스를 Weave로 전송하려면 먼저 OTEL 의존성을 설치하고 OTEL 익스포터를 설정해야 합니다. 필수 OTEL 의존성을 설치하세요:
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
그런 다음 Weave에서 OTEL 트레이싱을 설정합니다.

Weave에서 OTEL 트레이싱 구성하기

PydanticAI에서 Weave로 트레이스를 보내려면 TracerProviderOTLPSpanExporter를 사용해 OTEL을 설정하세요. 익스포터는 인증 및 프로젝트 식별에 필요한 올바른 엔드포인트와 HTTP 헤더로 설정하세요. API 키와 프로젝트 정보 같은 민감한 환경 변수는 환경 파일(예: .env)에 저장하고 os.environ을 사용해 불러오세요. 이렇게 하면 자격 증명을 안전하게 보호하고 코드베이스에 포함되지 않도록 할 수 있습니다.

필수 설정

  • 엔드포인트: https://trace.wandb.ai/otel/v1/traces
  • 헤더:
    • Authorization: W&B API 키를 사용하는 Basic 인증.
    • project_id: W&B entity 및 프로젝트 이름(예: myteam/myproject).

설정 예시

다음 코드 스니펫에서는 OTLP span 익스포터와 트레이서 프로바이더를 구성하여 PydanticAI 애플리케이션의 OTEL 트레이스를 Weave로 전송하는 방법을 보여줍니다.
import base64
import os
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# 환경 변수에서 민감한 값 로드
WANDB_BASE_URL = "https://trace.wandb.ai"
PROJECT_ID = os.environ.get("WANDB_PROJECT_ID")  # W&B entity/프로젝트 이름 예: "myteam/myproject"
WANDB_API_KEY = os.environ.get("WANDB_API_KEY")  # W&B API 키

OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"
AUTH = base64.b64encode(f"api:{WANDB_API_KEY}".encode()).decode()

OTEL_EXPORTER_OTLP_HEADERS = {
    "Authorization": f"Basic {AUTH}",
    "project_id": PROJECT_ID,
}

# 엔드포인트와 헤더로 OTLP span 익스포터 생성
exporter = OTLPSpanExporter(
    endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
    headers=OTEL_EXPORTER_OTLP_HEADERS,
)

# 트레이서 프로바이더 생성 및 익스포터 추가
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
이제 PydanticAI 에이전트에 전달해 OTEL 트레이스를 Weave로 라우팅할 수 있는 tracer_provider가 있습니다.

OTEL로 PydanticAI 에이전트 트레이스하기

PydanticAI 에이전트를 트레이스하고 트레이스 데이터를 Weave로 보내려면, 트레이서 프로바이더로 설정한 InstrumentationSettings 객체를 Agent 생성자에 전달하세요. 이렇게 하면 모든 에이전트와 도구 call이 OTEL 설정에 따라 트레이스됩니다. 다음 예제는 트레이싱을 활성화한 기본 에이전트를 만드는 방법을 보여줍니다. 핵심 step은 에이전트를 초기화할 때 instrument 인자를 설정하는 것입니다:
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# OTEL 트레이싱을 사용하는 PydanticAI 에이전트 생성
agent = Agent(
    "openai:gpt-4o",
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

result = agent.run_sync("What is the capital of France?")
print(result.output)
에이전트로의 모든 call은 트레이스되어 Weave로 전송됩니다.
기본 PydanticAI 에이전트의 트레이스 시각화

OTEL로 PydanticAI 도구 트레이스하기

Weave는 OTEL로 계측된 모든 PydanticAI 오퍼레이션을 트레이스할 수 있으며, 여기에는 에이전트 call과 도구 call이 모두 포함됩니다. 즉, 에이전트가 도구(예: @agent.tool_plain으로 데코레이팅된 함수)를 호출하면 도구 입력, 출력, 그리고 모델의 추론을 포함한 전체 상호작용이 Weave에서 캡처되어 시각화됩니다. 다음 예제는 system prompt와 도구를 포함하는 에이전트를 만드는 방법을 보여줍니다. 트레이싱은 에이전트와 도구 모두에 대해 자동으로 활성화됩니다:
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# system prompt와 OTEL 트레이싱으로 PydanticAI 에이전트 생성
agent = Agent(
    "openai:gpt-4o",
    system_prompt=(
        "You are a helpful assistant that can multiply numbers. "
        "When asked to multiply numbers, use the multiply tool."
    ),
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

# 도구 정의
@agent.tool_plain
def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

# 에이전트에게 도구 사용 요청
result = agent.run_sync("What is 7 multiplied by 8?")
print(result.output)
도구 call에 대한 트레이스 시각화
에이전트 call과 도구 call은 모두 Weave에서 트레이스되므로, 애플리케이션의 전체 추론 및 실행 경로를 확인할 수 있습니다.

기본적으로 모든 에이전트 계측

애플리케이션의 모든 PydanticAI 에이전트에 OTEL 트레이싱을 적용하려면 Agent.instrument_all()을 사용하세요. 이렇게 하면 instrument 매개변수를 명시적으로 지정하지 않은 모든 에이전트에 기본 InstrumentationSettings 인스턴스가 설정됩니다.
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# Set up default instrumentation for all agents
Agent.instrument_all(InstrumentationSettings(tracer_provider=tracer_provider))

# 이제 새로운 에이전트는 기본적으로 이 계측을 사용합니다
agent1 = Agent("openai:gpt-4o")
agent2 = Agent("openai:gpt-4o", system_prompt="Be helpful.")

result = agent1.run_sync("What is the capital of France?")
print(result.output)
설정을 반복하지 않고도 모든 에이전트에서 일관된 트레이싱을 유지하려는 대규모 애플리케이션에 유용합니다. 자세한 내용은 PydanticAI OTEL docs를 참조하세요.

더 알아보기