문제 해결(Troubleshooting)

아래는 Pydantic AI를 사용하면서 마주칠 수 있는 몇 가지 흔한 오류를 고치는 방법이에요. 겪고 있는 문제가 아래에 없거나 문서에서 다뤄지지 않았다면, Pydantic Slack에서 물어보거나 GitHub에 이슈를 만들어 주세요.

출처: 문서

본문

Jupyter Notebook 오류

`RuntimeError: This event loop is already running`

현대 Jupyter/IPython(7.0+): 이 환경은 최상위 await를 네이티브로 지원해요. 추가 설정 없이 노트북 셀에서 Agent.run()을 직접 사용할 수 있어요:

from pydantic_ai import Agent

agent = Agent('openai:gpt-5.2')
result = await agent.run('Who let the dogs out?')

레거시 환경 또는 특정 통합: 이벤트 루프 충돌이 발생하면 nest-asyncio를 사용하세요:

import nest_asyncio

from pydantic_ai import Agent

nest_asyncio.apply()

agent = Agent('openai:gpt-5.2')
result = agent.run_sync('Who let the dogs out?')

참고: 이것은 Google Colab과 Marimo 환경에도 적용돼요.

`RuntimeError: Event loop is closed`

Agent.run_sync() 같은 동기 메서드는 스레드의 현재 이벤트 루프를 재사용하고, 다른 코드가 닫았으면 새 루프를 설치해요. 모델 요청 중에 httpx2(또는 레거시 httpx) 내부에서 이 오류가 발생했다면, 에이전트가 이벤트 루프가 닫히기 전에 이미 사용된 것이에요. 프로바이더의 HTTP 연결 풀이 죽은 루프에 묶인 연결을 여전히 붙잡고 있기 때문이에요. 에이전트를 모델과 프로바이더와 함께 다시 만들거나(또는 프로바이더에 새 http_client를 전달), 기존 Model 인스턴스를 재사용하면 죽은 연결 풀을 유지해요. 다른 코드가 여전히 사용하는 이벤트 루프를 닫지 마세요.

`UserError`: `Agent.run_sync()`와 `Agent.run_stream_sync()`는 동기 툴, 출력 함수, 또는 에이전트 실행 중에 호출되는 다른 함수 안에서 사용할 수 없음

이 오류는 에이전트 실행 중에 호출된 동기 툴, 출력 함수, 또는 다른 함수가 Agent.run_sync()나 Agent.run_stream_sync()로 중첩 실행을 시작하려 했다는 뜻이에요. 동기 실행 메서드는 일반 애플리케이션 코드에서만, 실행 밖에서 사용할 수 있어요. 실행 안에서는 부모 실행이 여전히 당신의 함수를 기다리는 동안 중첩 실행이 그것을 막아 데드락이 생길 수 있으므로, Pydantic AI는 대신 이 오류를 발생시켜요.

위임 함수를 async def로 만들고 내부 실행을 await 하세요. 에이전트 위임에서 보여주는 것처럼요. 부모 에이전트는 여전히 일반 동기 애플리케이션 코드에서 run_sync()로 시작할 수 있어요. 위임 함수가 블로킹 작업도 해야 한다면 그 부분만 asyncio.to_thread()로 밀어 넣으세요.

API 키 구성

`UserError`: `[PROVIDER]_API_KEY` 환경 변수를 설정하거나 프로바이더의 `api_key=...` 인자로 전달하세요

모델의 API 키 설정에 문제가 있다면, Models 페이지를 방문해 환경 변수를 설정하거나 api_key 인자로 전달하는 방법을 배워 보세요.

API 키 없이 Pydantic AI를 시도하려면, 내장된 'test' 모델을 사용하세요: Agent('test').

HTTPX 요청 모니터링

모델에서 커스텀 httpx2(또는 레거시 httpx) 클라이언트를 사용해서 런타임에 특정 요청, 응답, 헤더에 접근할 수 있어요.

logfire의 HTTPX 통합을 사용해 위의 것을 모니터링하는 것이 특히 유용해요.

문제 해결(Troubleshooting)