파이썬 AI 에이전트 만들기: 도구·시스템 프롬프트와 크래시 복구 튜토리얼

핵심 메시지

• AI 에이전트 만들기는 ①에이전트가 쓸 도구 작성 ②에이전트 정의 ③실행 코드 작성의 세 단계로 나눌 수 있다.
• 도구는 에이전트가 호출하는 파이썬 함수이며, 함수 이름·타입 힌트·독스트링이 모두 에이전트에게 사용법을 알려주는 단서가 된다.
• 에이전트는 서버에서 실행되고 파이썬 프로세스는 클라이언트 역할만 하므로, 서버가 에이전트 상태를 보관한다.
• 서버가 상태를 소유하기 때문에 작업 도중 프로세스가 죽어도 실행 ID로 같은 실행을 이어서 복구할 수 있다.
• 재시도 시 결과가 중복되지 않으려면 도구 호출이 멱등(idempotent)해야 한다.

쉽게 이해하기

진행자 데이비드는 파이썬으로 첫 AI 에이전트를 단계별로 만든다. 무료 오픈소스 프레임워크 '에이전트 스팬(Agent Span)'을 사용하며, 사전 준비물로 파이썬 3.10 이상, JDK(촬영 시점 최신 LTS 25, 또는 21도 지원), 그리고 패키지 매니저 UV를 안내한다. 관련 링크는 설명란의 리소스 가이드에 있다.

VS 코드에서 빈 폴더를 열고 터미널에서 'uv init'으로 프로젝트를 만든 뒤 'uv add'로 에이전트 스팬과 의존성을 추가한다. 'uv run agent span doctor'로 설치를 점검하는데, AI 제공자 설정(로컬 Ollama, 또는 OpenAI·Anthropic API 키와 환경 변수)이나 맥에서 흔한 인증서 검증 오류 때문에 모두 초록색이 아닐 수 있고, 영상은 각 해결 명령을 안내한다.

에이전트는 세 단계로 작성한다. 먼저 도구는 에이전트가 호출하는 파이썬 함수로, 예시 'get_weather'에 @tool 데코레이터를 붙여 노출한다. 초보자가 놓치기 쉬운 점은 함수 이름, 매개변수·반환값의 타입 힌트, 독스트링이 모두 에이전트에게 이 도구의 용도와 사용법을 알려주는 단서라는 것이다. 다음으로 에이전트에는 이름, 'provider/model' 형식의 모델 이름, 도구 목록이 필요하다. 마지막 실행 코드는 에이전트 스팬 서버에 연결되는 런타임을 만들어 'runtime.run'에 프롬프트를 넘긴다. 에이전트는 서버에서 실행되고 파이썬 프로세스는 클라이언트일 뿐이다.

서버를 'uv run agent span server start'로 띄우고 'uv run main.py'로 에이전트를 실행하면, 로그에서 도구 호출과 출력을 확인할 수 있다. 서버에는 웹 대시보드가 있어 모든 실행(execution)이 기록되며, 실행 ID를 클릭하면 프롬프트→AI 모델→도구 호출→출력으로 이어지는 워크플로우를 시각적으로 보고 각 노드의 입력·출력을 살펴볼 수 있다. 이어서 가격 계산 모듈의 네 함수에 대한 단위 테스트를 작성하는 다단계 에이전트를 만들면, 네 번의 도구 호출이 병렬로 처리되는 것을 볼 수 있다.

핵심은 크래시 복구다. 에이전트 상태가 서버에 있어 'runtime.run' 대신 'runtime.start'로 실행하면 실행 ID가 담긴 핸들을 받는다. 도구가 2초씩 대기하도록 해 둔 상태에서 작업 중간에 프로세스를 강제 종료하면 서버에는 어떤 도구 호출도 완료되지 않은 것으로 남는데, 그 실행 ID를 다시 지정해 실행하면 새로 시작하지 않고 기존 실행을 이어받아 네 개의 테스트를 모두 완성한다. 이때 결과가 중복되지 않은 이유는 이미 파일에 있으면 다시 쓰지 않도록 도구를 멱등하게 만들었기 때문이다. 상태가 서버에 있으므로 파이썬 스크립트가 죽거나 다른 컴퓨터로 옮겨도 에이전트는 작업을 계속 이어간다.

주요 인사이트

• 도구 함수의 이름·타입 힌트·독스트링은 단순 문서가 아니라 에이전트가 도구를 언제 어떻게 호출할지 판단하는 정보이므로, 부실하면 필요한 순간에도 호출되지 않을 수 있다.
• 에이전트를 서버에서 실행하고 파이썬을 클라이언트로 두면, 실행 상태가 서버에 보관돼 프로세스 크래시·재시작·머신 이동에도 작업이 이어진다.
• 크래시 후 같은 실행을 이어가려면 'runtime.start'가 돌려주는 실행 ID(핸들)를 보관했다가 재개에 사용해야 한다.
• 재시도가 결과를 중복 생성하지 않으려면, 같은 호출을 여러 번 해도 결과가 같은 멱등한 도구 설계가 필요하다.
• 여러 도구 호출은 병렬로 처리될 수 있고, 대시보드에서 각 실행과 도구 호출의 입력·출력을 추적해 디버깅할 수 있다.

자주 묻는 질문

관련 AI 소식