> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PydanticAI

> Weave에서 OpenTelemetry를 사용하여 PydanticAI 에이전트와 도구 Call을 트레이스하세요

[PydanticAI](https://ai.pydantic.dev/) 에이전트와 도구 Call을 Weave에서 [OpenTelemetry (OTEL)](https://opentelemetry.io/)를 사용하여 트레이스할 수 있습니다. PydanticAI는 Pydantic 팀이 구축한 Python 에이전트 프레임워크로, 생성형 AI를 사용하여 프로덕션급 애플리케이션을 간단하고 타입 안전하게 구축할 수 있도록 합니다. 모든 에이전트와 도구 Call을 트레이싱하기 위해 OTEL을 사용합니다.

<Tip>
  Weave의 OTEL 트레이싱에 대한 자세한 내용은 [Weave에 OTEL 트레이스 보내기](/ko/products/wandb/weave/guides/tracking/otel)를 참조하세요.
</Tip>

이 가이드는 Weave에서 에이전트와 도구 실행에 대한 가시성을 원하는 PydanticAI 에이전트를 구축하는 개발자를 위한 것입니다. OTEL을 사용하여 PydanticAI 에이전트와 도구 Call을 트레이스하고 Weave에서 해당 트레이스를 시각화하는 방법을 보여줍니다. 의존성을 설치하고, Weave로 데이터를 전송하기 위해 OTEL 트레이서를 설정하며, PydanticAI 에이전트와 도구를 계측하는 방법을 배웁니다. 또한 애플리케이션의 모든 에이전트에서 기본적으로 트레이싱을 활성화하는 방법도 확인할 수 있습니다.

<h2 id="prerequisites">
  사전 요구 사항
</h2>

Weave에 트레이스를 전송하려면 OTEL 의존성을 설치하고 OTEL 익스포터를 설정해야 합니다. 필수 OTEL 의존성을 설치하세요:

```bash theme={"system"}
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

그런 다음, [Weave에서 OTEL 트레이싱 설정](#configure-otel-tracing-in-weave).

<h3 id="configure-otel-tracing-in-weave">
  Weave에서 OTEL 트레이싱 설정
</h3>

PydanticAI에서 Weave로 트레이스를 보내려면 `TracerProvider`와 `OTLPSpanExporter`로 OTEL을 설정하세요. 익스포터에는 [인증 및 프로젝트 식별에 필요한 올바른 엔드포인트와 HTTP 헤더](#required-configuration)를 지정하세요.

API 키나 프로젝트 정보 같은 민감한 환경 변수는 환경 파일(예: `.env`)에 저장하고 `os.environ`으로 불러오세요. 이렇게 하면 자격 증명을 코드베이스와 분리해 안전하게 보관할 수 있습니다.

<h3 id="required-configuration">
  필수 설정
</h3>

* **엔드포인트:** `https://trace.wandb.ai/otel/v1/traces`
* **헤더:**
  * `Authorization`: W\&B API 키를 사용한 기본 인증.
  * `project_id`: W\&B entity와 프로젝트 이름 (예: `myteam/myproject`).

<h3 id="example-setup">
  예시 설정
</h3>

다음 코드 스니펫은 PydanticAI 애플리케이션에서 OTEL 트레이스를 Weave로 전송하기 위해 OTLP span 익스포터와 트레이서 프로바이더를 설정하는 방법을 보여줍니다.

```python lines theme={"system"}
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 키

WEAVE_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,
}

# endpoint와 헤더를 사용하여 OTLP span 익스포터를 생성합니다
exporter = OTLPSpanExporter(
    endpoint=WEAVE_OTLP_ENDPOINT,
    headers=OTEL_EXPORTER_OTLP_HEADERS,
)

# 트레이서 프로바이더를 생성하고 익스포터를 추가합니다
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
```

이제 `tracer_provider`를 PydanticAI 에이전트에 전달하여 OTEL 트레이스를 Weave로 라우팅할 수 있습니다.

<h2 id="trace-pydanticai-agents-with-otel">
  PydanticAI 에이전트를 OTEL로 트레이스
</h2>

PydanticAI 에이전트를 트레이스하고 트레이스 데이터를 Weave로 전송하려면, 트레이서 프로바이더로 설정된 `InstrumentationSettings` 객체를 `Agent` Constructor에 전달하세요. 이렇게 하면 모든 에이전트와 도구 Call이 OTEL 설정에 따라 트레이스됩니다.

다음 예시는 트레이싱이 활성화된 기본 에이전트를 만드는 방법을 보여줍니다. 핵심 단계는 에이전트를 초기화할 때 `instrument` 인수를 설정하는 것입니다:

```python lines theme={"system"}
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로 전송됩니다.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/weave/_media/pydanticai_agent_trace.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=f2f1eb9fc9deea12e26eddb5a730f7ec" alt="기본 PydanticAI 에이전트의 트레이스 시각화" width="2910" height="1594" data-path="products/wandb/weave/_media/pydanticai_agent_trace.png" />
</Frame>

<h2 id="trace-pydanticai-tools-with-otel">
  PydanticAI 도구를 OTEL로 트레이스하기
</h2>

Weave는 OTEL로 계측된 모든 PydanticAI 오퍼레이션을 트레이스할 수 있으며, 에이전트와 도구 Call을 모두 포함합니다. 즉, 에이전트가 도구(예: `@agent.tool_plain`으로 데코레이트된 함수)를 호출할 때, 도구 입력, 출력, 모델의 추론을 포함한 전체 상호작용이 Weave에서 캡처되어 시각화됩니다.

다음 예시는 system 프롬프트와 도구가 있는 에이전트를 만드는 방법을 보여줍니다. 에이전트와 도구 모두에 대해 트레이싱이 자동으로 활성화됩니다:

```python lines theme={"system"}
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# PydanticAI 에이전트를 system 프롬프트와 OTel 트레이싱으로 생성합니다
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)
```

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/weave/_media/pydanticai_tool_call.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=56bcdd0ce8a0fb0c00ef790632dda6e8" alt="도구 Call의 트레이스 시각화" width="2912" height="1592" data-path="products/wandb/weave/_media/pydanticai_tool_call.png" />
</Frame>

에이전트 call과 도구 Call은 모두 Weave에서 traced되어 애플리케이션의 전체 추론 및 실행 경로를 검사할 수 있습니다.

<h2 id="instrument-all-agents-by-default">
  모든 에이전트에 기본적으로 계측 적용
</h2>

애플리케이션의 모든 PydanticAI 에이전트에 OTel 트레이싱을 적용하려면 `Agent.instrument_all()` 방법을 사용하세요. 이렇게 하면 `instrument` 매개변수를 명시적으로 지정하지 않은 모든 에이전트에 대해 기본 `InstrumentationSettings` 인스턴스를 설정합니다.

```python lines theme={"system"}
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# 모든 에이전트에 대한 기본 계측 설정
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](https://ai.pydantic.dev/logfire/#using-logfire)를 참조하세요.

<h2 id="learn-more">
  자세히 알아보기
</h2>

* [Weave 문서: Weave에 OTEL 트레이스 보내기](/ko/products/wandb/weave/guides/tracking/otel)
* [공식 OTEL 문서](https://opentelemetry.io/)
* [공식 PydanticAI 문서](https://ai.pydantic.dev/)
* [PydanticAI GitHub 저장소](https://github.com/pydantic/pydantic-ai)