Pydantic AI

Pydantic AI

Pydantic 검증 위에 세워진 Python 네이티브 LLM 에이전트 프레임워크인 Pydantic AI를 쓰고 있다면, 에이전트를 평소처럼 만들면서도 추적을 시작할 수 있어요. Confident AI의 OpenTelemetry 네이티브 추적 SDK인 confident-trace로 Pydantic AI 에이전트를 추적·평가하세요. init()을 한 번 호출하면 됩니다.

출처: 문서

본문

개요

Pydantic AI는 Pydantic 검증 기반 위에 세워진 Python 네이티브 LLM 에이전트 프레임워크입니다. Confident AI는 OpenTelemetry 네이티브 추적 SDK인 confident-trace로 Pydantic AI 에이전트를 추적·평가할 수 있게 해 줘요 — init()을 한 번 호출하면 Agent를 지금처럼 그대로 만들면 됩니다.

Pydantic AI가 스팬을 스스로 만들기 때문에, 이 통합은 export 전용 경로예요. 도구 안이나 에이전트 실행 밖에서 하는 모델 호출은 OpenAI 같은 프로바이더 통합이 여전히 추적합니다 — 모두 같은 init()으로 활성화돼요.

Runtime Requirements Setup
Python Python 3.10+, pydantic-ai or pydantic-ai-slim (tested with 2.40.0) Call init() before running the agent
TypeScript Not supported —

자동 계측

의존성 설치

confident-trace를 Pydantic AI 및 에이전트가 쓰는 모델 SDK와 함께 설치하세요(예제는 OpenAI 사용).

pip install confident-trace 'pydantic-ai-slim[openai]'

API 키 설정

Confident AI Project API key를 받아 모델 프로바이더 키와 함께 환경 변수로 설정하세요.

export CONFIDENT_API_KEY="<your-confident-project-key>"
export OPENAI_API_KEY="<your-openai-key>"

EU 리전이거나 자체 호스팅 배포라면, 트레이스가 우리 US 서버로 가지 않도록 CONFIDENT_OTEL_ENDPOINT도 설정하세요 — init() 구성을 참고하세요.

Pydantic AI 계측

에이전트를 실행하기 전에 init()을 한 번 호출하세요. pydantic_ai에서 Agent를 평소처럼 만들면 돼요 — instrument=에 넘길 것은 없습니다.

동기

from confident_trace import init, shutdown
from pydantic_ai import Agent

init()
agent = Agent("openai:gpt-4.1-mini", system_prompt="Be concise, reply with one sentence.")

try:
    result = agent.run_sync("What are LLMs?")
    print(result.output)
finally:
    shutdown()

비동기

import asyncio
from confident_trace import init, shutdown
from pydantic_ai import Agent

init()
agent = Agent("openai:gpt-4.1-mini", system_prompt="Be concise, reply with one sentence.")

async def main():
    result = await agent.run("What are LLMs?")
    print(result.output)

try:
    asyncio.run(main())
finally:
    shutdown()

스트리밍

import asyncio
from confident_trace import init, shutdown
from pydantic_ai import Agent

init()
agent = Agent("openai:gpt-4.1-mini", system_prompt="Be concise, reply with one sentence.")

async def main():
    async with agent.run_stream("What is the weather in London?") as result:
        async for chunk in result.stream_text(delta=True):
            print(chunk, end="", flush=True)
        final = await result.get_output()
        print("\n\nFinal:", final)

try:
    asyncio.run(main())
finally:
    shutdown()

장기 실행 서버에서는 시작 시 init()을 한 번, 정상 종료 시 활성 에이전트 실행이 끝난 뒤 shutdown()을 한 번 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

Pydantic AI 실행

스크립트를 실행해 트레이스를 Confident AI로 보내세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 에이전트·모델·도구 스팬을 확인하세요.

트레이스가 안 보이면 99.99% 프로그램이 스팬을 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

Pydantic AI의 네이티브 스팬이 원래 ID, 부모, 이벤트, 속성과 함께 내보내져서, Observatory에서 보는 것은 Pydantic AI가 보고하는 구조 그대로예요.

  • 에이전트 실행, 모델 요청, 도구 실행 — Pydantic AI가 보고하는 계층 그대로
  • 모델 콘텐츠 — Pydantic AI가 포착한 프롬프트·완성, 프레임워크에서 기본적으로 켜져 있음
  • 비동기 실행·스트림 — agent.run과 agent.run_stream이 같은 init() 설정으로 포함됨

Confident의 OpenAI·Anthropic·Google GenAI 통합은 현재 스팬이 같은 프로바이더의 인식된 Pydantic AI 모델 스팬일 때만 호출을 건너뛰므로, 중복 모델 스팬이 보이지 않아요. 직접 SDK 호출과 도구 함수 안의 SDK 호출은 자체 Confident LLM 스팬을 받습니다.

도구와 스트리밍

Pydantic AI의 데코레이터로 정의한 도구는 네이티브 계측이 포착합니다 — Confident 데코레이터는 필요 없어요. 이 조각들은 빠른 시작의 try 블록 안 agent.run_sync 호출을 대체합니다.

import asyncio

@agent.tool_plain
def get_weather(city: str) -> str:
    return f"{city}: sunny, 22°C"

async def main():
    async with agent.run_stream("What is the weather in Tokyo?") as stream:
        async for chunk in stream.stream_text(delta=True):
            print(chunk, end="", flush=True)

asyncio.run(main())

shutdown() 전에 스트림을 마치거나 닫으세요. Pydantic AI는 취소·조기 닫기 시 스팬을 닫지만, shutdown 시점에 여전히 열려 있는 스트림은 트레이스를 불완전하게 남겨요. flush와 shutdown을 참고하세요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. agent.run_sync()가 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context
from pydantic_ai import Agent

init()

agent = Agent("openai:gpt-4.1-mini", system_prompt="Be concise.")

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = agent.run_sync("Explain OpenTelemetry in one sentence.")

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

Pydantic AI 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 Pydantic AI 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = agent.run_sync("Find the relevant account details.")
    answer = agent.run_sync(f"Summarize these details: {context.output}")

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

트러블슈팅

  • 트레이스 없음: 에이전트가 실행되기 전에 init()이 실행되고, 프로세스가 shutdown()에 도달해 버퍼링된 스팬이 플러시되며, 에이전트에서 Pydantic AI의 계측이 꺼져 있지 않은지(agent.instrument = False) 확인하세요.
  • 중복 모델 스팬: 두 번째 프로바이더 instrumentor가 붙어 있어요. 외부 계측이 프로바이더 호출을 이미 다룬다면 init(instrumentations=())을 전달하세요.
  • 콘텐츠 누락: 네이티브 스팬 콘텐츠는 capture_content가 아니라 Pydantic AI의 InstrumentationSettings가 제어합니다.
  • 스팬이 다른 곳으로 감: Pydantic AI가 자체 tracer 프로바이더로 구성됐다면, 그 프로바이더를 init(tracer_provider=...)에 전달하고 전역으로 등록하세요. 초기화 전에 같은 프로바이더를 전역 등록하세요.

일반적인 문제는 트러블슈팅을 참고하세요.

Pydantic AI 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. Pydantic AI의 식별자는 Python에서 "pydantic_ai"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("pydantic_ai",) to opt in; omit "pydantic_ai" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 프로덕션 AI 품질을 모니터링하세요.

Threads

다중 턴 에이전트 대화를 스레드로 묶고, 턴 입출력을 설정하며, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

  • OpenAI — 공식 OpenAI 클라이언트 추적
  • Threads — 에이전트 대화를 스레드로 묶어 평가
  • Online Evals — 실시간 트레이스·스팬 평가