구글 ADK LLM 에이전트 입문 — 폴더 규칙부터 웹 UI 테스트까지 실습 정리

핵심 메시지

• ADK의 모든 에이전트는 베이스 에이전트를 뿌리로 삼고, 그 위에 LLM 에이전트·워크플로 에이전트·커스텀 에이전트 세 갈래가 놓인다.
• LLM 에이전트는 정해진 흐름 없이 모델이 스스로 판단해 도구를 부르거나 다른 에이전트에 일을 넘긴다.
• 에이전트 하나를 정의하는 데 필요한 핵심 설정은 이름, 모델, 설명, 지침 네 가지다.
• ADK가 에이전트를 인식하려면 폴더에 __init__.py, agent.py, .env 세 파일이 규칙대로 있어야 하고 진입점 변수 이름은 root_agent 여야 한다.
• adk web 명령으로 뜨는 개발자 웹 UI의 트레이스 탭에서 호출된 에이전트와 요청·응답, 사용한 도구까지 확인할 수 있다.

쉽게 이해하기

이 강의는 구글이 내놓은 에이전트 개발 키트(ADK)를 다루는 연속 강좌의 첫 실습 회차다. 강연자는 ADK에서 에이전트를 '특정 목표를 위해 자율적으로 움직이는 독립된 실행 단위'로 정의한다. 에이전트는 작업을 수행하고 사용자와 대화하며 외부 도구를 쓰고 다른 에이전트와 협력할 수 있는데, 이 모든 형태의 뿌리에 베이스 에이전트가 있다.

베이스 에이전트를 물려받는 구현체는 세 가지다. 가장 기본이 되는 LLM 에이전트, 여러 에이전트의 실행 순서를 결정론적인 패턴으로 통제하는 워크플로 에이전트, 그리고 개발자가 고유한 제어 흐름을 직접 짜 넣는 커스텀 에이전트다. 강연자는 이 셋을 조합하면 모델의 자율적인 판단부터 정해진 절차의 통제까지 폭넓은 요구를 감당할 수 있다고 설명한다.

LLM 에이전트는 대형 언어 모델을 두뇌로 삼아 사용자 입력을 이해하고 답을 만든다. 겉보기에는 흔한 대화형 서비스와 비슷하지만, 도구를 직접 호출하고 스스로 다음 행동을 정한다는 점이 다르다. 정의에 필요한 설정은 네 가지다. 다른 에이전트가 참조하고 작업을 넘길 때 쓰는 고유한 이름, 두뇌로 쓸 모델, 위임 대상을 고를 때 판단 근거가 되는 짧은 설명, 그리고 행동을 좌우하는 지침이다. 강연자는 이 가운데 지침이 성능을 가장 크게 좌우한다고 강조한다.

실습은 개발 환경부터 시작한다. 파이썬 가상 환경을 만들고 google-adk 패키지를 설치한 뒤, 에이전트 폴더에 세 개의 파일을 규칙대로 배치한다. 패키지로 인식시키는 __init__.py, 에이전트를 실제로 구현하는 agent.py, API 키 같은 민감한 값을 담는 .env다. 예제에서는 제미나이를 쓰기 위해 구글 AI 스튜디오에서 발급한 키와 버텍스 AI 사용 여부 설정을 .env에 넣었고, 만든 인스턴스를 root_agent 라는 이름의 변수에 담아 ADK가 진입점을 찾을 수 있게 했다.

완성한 '웰컴 에이전트'는 이름을 물어본 뒤 그 이름으로 인사하는 아주 단순한 예제지만, 확인 방법이 인상적이다. adk web 명령을 실행하면 개발자 웹 UI 주소가 나오고, 여기서 대화를 걸어 의도대로 동작하는지 살필 수 있다. 특히 트레이스 탭에는 어떤 에이전트가 호출됐고 요청과 응답이 어떻게 오갔는지가 순서대로 남는다. 도구를 붙인 에이전트라면 어떤 도구를 골라 썼는지까지 확인할 수 있다.

주요 인사이트

• ADK의 설계에서 '설명' 항목은 사람을 위한 주석이 아니라 다른 에이전트가 위임 대상을 고를 때 읽는 정보다. 멀티 에이전트를 염두에 둔다면 짧아도 구별되게 써야 한다.
• 폴더 구조와 변수 이름을 프레임워크가 규칙으로 강제한다는 점은 초기 진입 장벽을 낮추는 대신, 규칙을 어기면 에이전트가 아예 인식되지 않는다는 뜻이기도 하다.
• 예제는 제미나이를 쓰지만 모델 항목만 바꾸면 다른 회사의 모델도 지정할 수 있다는 설명이 나온다. 특정 모델에 묶이지 않는 구조라는 점이 ADK의 장점으로 제시된다.
• 트레이스 화면은 단순한 로그가 아니라 에이전트가 왜 그렇게 행동했는지 되짚는 창구다. 도구 호출이 늘어날수록 이 기록의 가치가 커진다.
• 발급한 API 키를 코드 저장소에 남기지 말라는 당부가 실습 중간에 나온다. 에이전트 개발에서 흔히 빠지는 함정을 초반에 짚어 준 셈이다.

자주 묻는 질문

관련 AI 소식