🐍01. 설치·헬로월드: 첫 Agent 실행

처음 목표는 복잡하지 않습니다. 내 컴퓨터에서 Agent를 1회 실행하고, 출력을 재현 가능하게 남기는 것입니다. 이 단계에서 중요한 건 화려한 프롬프트가 아니라 실행 환경과 최소 코드 구조를 고정하는 일입니다.

AI 활용 안내: 이 문서는 생성형 AI를 활용해 작성했으며, Pydantic AI 공식 문서를 1차 출처로 검토해 정리했습니다.

공식문서 흐름 점검 (개요 보완)

흐름: 설치(install) → 모델 공급자 선택(models/overview) → 최소 실행(agent) → 실행 모드 차이(run_sync vs run) → 기본 트러블슈팅(API Key/환경변수).
이번 편에서 빠지면 안 되는 포인트:
- 일반 설치와 slim 설치 차이를 초반에 구분한다.
- 첫 실행 성공 조건을 “응답 생성”이 아니라 모델 연결 + 예외 없이 종료로 정의한다.
- 로컬 개발에서 가장 흔한 실패(키 누락, provider mismatch)를 체크리스트에 포함한다.
공식 문서 체크 링크:

10분 안에 끝내는 설치 루틴

Pydantic AI 공식 설치 문서는 pydantic-ai 기본 설치와 pydantic-ai-slim[...] 경량 설치를 분리해서 안내합니다. 처음에는 기본 설치가 시행착오를 줄입니다.

기본 설치: pip install pydantic-ai 또는 uv add pydantic-ai
Python 권장 버전: 3.10+

공식 문서: https://ai.pydantic.dev/install/

flowchart LR
  A[Python 3.10+ 확인] --> B[pydantic-ai 설치]
  B --> C[API Key 환경변수 설정]
  C --> D[hello_agent.py 실행]
  D --> E[run_sync 결과 확인]

가장 작은 실행 코드

Agent를 만들고 run_sync()로 한 줄 질의를 던지면 첫 단계는 완료입니다.

from pydantic_ai import Agent
 
agent = Agent('openai:gpt-5.2', instructions='한 문장으로 짧게 답해줘.')
result = agent.run_sync('서울에서 비 오는 날 우산 팁 1개만 알려줘')
print(result.output)

공식 참고: Agent 실행 방식(run, run_sync, run_stream)
https://ai.pydantic.dev/agent/

미니 사례 A: 설치는 됐는데 모델 호출이 실패한 경우

한 팀은 패키지는 정상 설치됐지만 모델 인증 키 누락으로 첫 실행이 실패했습니다. 이때 코드부터 고치기보다, .env/환경변수 로딩 순서를 먼저 고정하니 5분 내 해결됐습니다.

실무 팁:

python -V 확인
설치 로그 확인
API 키 존재 여부 확인
같은 프롬프트로 3회 재실행

미니 사례 B: 설치는 쉬운데 의존성 충돌이 나는 경우

다른 팀은 기존 프로젝트 의존성과 충돌이 났습니다. 전역 설치 대신 프로젝트 로컬 가상환경으로 분리하고, pydantic-ai-slim[openai]로 좁히니 충돌이 크게 줄었습니다.

공식 문서: https://ai.pydantic.dev/install/#slim-install

실행 체크리스트 (성공 판정)

run_sync()로 실제 문자열 결과를 받았다
동일 질문 3회 실행 시 예외 없이 완료됐다
코드 파일을 팀원이 받아도 같은 절차로 재실행 가능하다

일하는 ai

탐색기