순수 파이썬 AI 에이전트 만들기 — 구조화 출력·도구 호출·워크플로 패턴 정리

핵심 메시지

• 많은 프레임워크가 AI 에이전트를 쉽게 만들어준다고 하지만, 종종 LLM API를 직접 다루는 것이 가장 효과적이다.
• 핵심 구성 요소는 구조화 출력, 도구(함수) 호출, 메모리, 검색 네 가지로, 이를 조합해 시스템을 만든다.
• 도구 호출에서 AI는 함수를 직접 실행하지 않고 필요한 매개변수만 제공하며, 실제 실행은 개발자 코드가 한다.
• 복잡한 작업은 프롬프트 체이닝·라우팅·병렬화 세 가지 워크플로 패턴의 조합으로 안정적으로 처리할 수 있다.
• 성공의 열쇠는 "사람이라면 어떻게 풀까"를 먼저 그려보고, 정말 필요한 곳에만 AI를 쓰는 것이다.

쉽게 이해하기

발표자 Dave Ebbelaar는 드래그 앤 드롭으로 에이전트를 만들어준다는 도구들이 많지만, 실제로는 대형 언어 모델의 API를 파이썬으로 직접 다루는 것이 가장 효과적인 경우가 많다고 말한다. 이 영상은 Anthropic의 "Building Effective Agents" 글에서 소개한 빌딩 블록과 패턴을 코드로 따라가며 설명한다.

가장 기본은 API에 직접 호출해 텍스트를 받는 것이지만, 실무에서는 더 많은 제어가 필요하다. 그래서 구조화 출력(structured output)을 사용한다. Pydantic으로 데이터 모델을 정의하면, 모델이 캘린더 일정의 이름·날짜·참석자처럼 정해진 형식의 키-값을 채워 돌려줘 프로그램에서 바로 활용할 수 있다.

다음은 도구 호출이다. 날씨 API를 도구로 정의해 두면 AI는 질문 맥락을 보고 도구 사용 여부를 결정한다. 중요한 점은 AI가 함수를 직접 실행하지 않고 위도·경도 같은 매개변수만 제공한다는 것이다. 실제 함수 실행과 결과 반영은 개발자의 스크립트가 책임진다. 같은 원리로 사내 지식베이스를 검색하는 도구를 붙이면 검색(retrieval)도 구현된다.

이 기본기 위에 워크플로 패턴을 얹는다. 프롬프트 체이닝은 작업을 단계로 쪼개 각 단계의 출력을 다음 단계로 넘기며, 중간에 "게이트"(if 문)를 두어 캘린더 일정이 아니거나 확신도가 낮으면 흐름을 중단한다. 라우팅은 조건에 따라 새 일정 생성·기존 일정 수정 등 서로 다른 호출로 분기한다.

마지막 패턴은 병렬화다. 서로 의존하지 않는 API 호출을 async 함수로 동시에 실행해 지연 시간을 줄인다. 발표자는 가드레일(예: 프롬프트 인젝션 탐지와 일정 판별)을 동시에 검사하는 예시로 이를 보여준다. 결국 모든 에이전트는 이 구성 요소들을 문제에 맞게 도표로 엮은 것일 뿐이라고 강조한다.

주요 인사이트

• 프레임워크는 학습에 유용하지만, 그 밑에 깔린 원리를 모른 채 의존하면 진짜 이해를 놓치기 쉽다.
• 도구 호출의 본질은 "AI가 매개변수를 제안하고, 실행은 코드가 한다"는 역할 분담이다.
• 메모리는 특별한 기술이 아니라 주고받은 메시지 목록을 계속 유지하는 것에 불과하다.
• 프롬프트 체이닝은 단계를 나눠 디버깅과 신뢰성을 크게 높여준다 — 어느 단계가 잘못됐는지 바로 보인다.
• 병렬화는 응답을 사용자가 직접 기다리는 앱에서 특히 효과적이며, 백엔드 배치 처리에서는 큰 차이가 없다.
• AI 에이전트는 어수선한 업무 위에 붙이는 반창고가 되어서는 안 되며, 먼저 프로세스 자체를 정리해야 한다.

자주 묻는 질문

관련 AI 소식