구글 ADK 커스텀 에이전트 구현 정리: BaseAgent 상속과 조건 분기 오케스트레이션 실습

핵심 메시지

• ADK의 모든 에이전트는 BaseAgent에서 출발하며, 그 위에 텍스트 생성과 도구 호출을 담당하는 LLM 에이전트와 순차·반복·병렬 흐름을 제어하는 워크플로우 에이전트가 표준으로 제공된다.
• 표준 워크플로우 에이전트는 정해진 방식대로만 쓸 수 있어서, 실행 도중 결과에 따라 경로가 갈리거나 외부 API 호출 결과로 다음 단계가 바뀌는 흐름은 구현하기 어렵다.
• 커스텀 에이전트는 BaseAgent를 상속하고 비동기 실행 메서드를 재정의해 개발자가 실행 로직과 흐름을 직접 설계하는 방식으로, ADK에서 가장 유연한 에이전트 유형이다.
• 실행 컨텍스트의 세션 상태가 단계 사이의 데이터 통로 역할을 하고, 하위 에이전트가 지정한 출력 키의 결과가 자동으로 상태에 기록되어 조건 분기의 근거가 된다.
• 실습 예제인 스토리 플로우 에이전트는 초안 작성, 비평·수정 반복, 문법 검사와 톤 분석 순차 실행, 톤 결과에 따른 재생성 분기까지를 하나의 커스텀 에이전트 안에서 조합한다.

쉽게 이해하기

구글 ADK로 에이전트를 만들 때 처음 배우는 것은 표준 구성 요소다. 모든 에이전트는 기본 구조와 인터페이스를 제공하는 BaseAgent에서 출발하고, 그 위에 두 종류가 놓인다. 하나는 텍스트 생성과 추론, 외부 도구 호출을 담당하는 LLM 에이전트로 각각 특정 역할을 맡은 두뇌 역할을 한다. 다른 하나는 여러 에이전트를 순차·반복·병렬 구조로 실행시키는 워크플로우 에이전트다. 문제는 이 둘이 ADK가 미리 정해 둔 방식이라 내부 로직이나 흐름을 마음대로 바꾸기 어렵다는 점이다.

강의는 커스텀 에이전트가 필요한 상황을 다섯 가지로 정리한다. 실행 도중 결과에 따라 다른 경로나 다른 하위 에이전트로 갈라져야 할 때, 단순 전달을 넘어 데이터를 계속 유지하고 갱신해야 할 때, 흐름 도중 외부 API나 데이터베이스를 호출해야 할 때, 진행 상황이나 입력값에 따라 다음에 실행할 에이전트를 유동적으로 바꿔야 할 때, 그리고 기존 순차·루프·병렬 구조로 표현하기 힘든 새로운 패턴이 필요할 때다.

구현의 핵심은 BaseAgent를 상속한 클래스를 만들고 비동기 실행 메서드를 재정의하는 것이다. 이 메서드는 단계별 결과를 이벤트로 계속 내보내는 비동기 제너레이터 형태여서, 하위 에이전트를 실행하든 도구를 쓰든 그 결과를 즉시 바깥으로 전달할 수 있다. 인자로 받는 실행 컨텍스트에는 현재 실행 정보가 들어 있고, 그 안의 세션 상태를 통해 앞 단계에서 저장한 값을 꺼내 조건 판단에 쓰거나 새 값을 저장해 다음 단계로 넘길 수 있다. 메서드 안에서는 파이썬의 조건문과 반복문, 예외 처리를 그대로 쓸 수 있어서, 하위 에이전트 호출과 상태 공유와 흐름 제어를 자유롭게 조합하는 구조가 된다.

실습 예제인 스토리 플로우 에이전트는 다섯 개의 LLM 하위 에이전트로 구성된다. 주제를 받아 초안을 쓰는 생성기, 초안을 비평하는 크리틱, 피드백을 반영해 고치는 리바이저, 문법을 확인하는 검사기, 전체 분위기를 판정하는 톤 분석기다. 비평과 수정은 최대 반복 횟수를 지정한 루프 에이전트로 묶고, 문법 검사와 톤 분석은 시퀀셜 에이전트로 묶은 뒤, 이 조합 전체를 커스텀 에이전트의 실행 메서드가 순서대로 호출한다.

마지막 단계가 커스텀 에이전트를 쓰는 이유를 보여 준다. 톤 분석기가 저장한 결과를 세션 상태에서 꺼내 부정적이면 스토리를 처음부터 다시 생성하고, 긍정적이면 그대로 종료하는 조건 분기다. 또한 초안 생성 직후 결과가 비어 있으면 워크플로우를 중단하는 방어 로직도 같은 메서드 안에 들어간다. 이런 분기는 표준 워크플로우 에이전트만으로는 표현하기 어렵다.

주요 인사이트

• 커스텀 에이전트를 쓴다고 표준 워크플로우를 버리는 것이 아니다. 실습에서는 비평·수정 반복을 루프 에이전트로, 문법 검사와 톤 분석을 시퀀셜 에이전트로 묶은 뒤 그 묶음을 커스텀 에이전트 안에서 호출한다. 표준 블록을 재료로 쓰고 그 사이를 잇는 판단만 직접 짜는 셈이다.
• 조건 분기의 근거는 결국 세션 상태다. 각 하위 에이전트가 출력 키를 지정하면 결과가 자동으로 상태에 기록되고, 상위 오케스트레이터는 그 값을 읽어 다음 행동을 정한다. 톤 분석기가 긍정·부정 중 한 단어만 출력하도록 프롬프트를 좁힌 것도 분기 판정을 단순하게 만들기 위한 설계다.
• 루프 에이전트에는 최대 반복 횟수를 반드시 지정해야 한다. 무한 반복을 막는 안전장치이며, 실습에서는 비평·수정 사이클을 두 번으로 제한했다.
• ADK는 실행 시작점으로 루트 에이전트라는 이름을 자동으로 찾기 때문에, 커스텀 에이전트 인스턴스를 만들 때 변수명을 반드시 루트 에이전트로 지정해야 한다는 규칙이 있다.
• 초기화 함수는 단순한 변수 세팅이 아니다. 하위 에이전트를 조합하고 실행 순서를 정의한 뒤 부모 초기화를 호출해, 흩어진 에이전트들을 실제로 실행 가능한 하나의 루트 구조로 조립하는 단계다.

자주 묻는 질문

관련 AI 소식