Google 의 Agent Development Kit (ADK) 을 사용하여 에이전트를 개발하고 계신다면, 동작 확인을 위해 내장된 Web UI 를 사용하고 싶은 경우가 많을 것입니다.
adk web
코맨드로 간편하게 개발 서버를 시작할 수 있다는 점은 편리하지만, 원격 개발 서버에서 실행하면 내 브라우저에서 액세스할 수 없다는 문제를 직면하는 경우가 있습니다.
이 글에서는 그 원인과 해결책을 정리합니다.
ADK (Agent Development Kit) 는 Google 이 공개한 AI 에이전트용 개발 키트입니다. Python 을 포함한 여러 언어에 대응하며, Gemini 를 제외한 모델과 함께 사용할 수 있습니다.
ADK 에는 브라우저 기반의 Web UI 가 포함되어 있습니다. adk web
를 실행하면 로컬에 개발 서버가 시작되어 채팅 화면에서 에이전트와 대화할 수 있습니다. 개발 전용이지만 동작 확인에는 매우 유용합니다.
adk web
은 기본적으로 127.0.0.1
(루프백 주소) 에만 bind 하지 않습니다. 이는 그 머신 자체에서만 액세스 가능함을 의미합니다.
원격 서버에서 개발하는 경우, 서버의 브라우저를 직접 조작할 수 없으며 내 PC 에서 확인하지 못하면 지루하게 불편합니다.
시작 시 --host
옵션을 지정하면 해결됩니다.
adk web --host 0.0.0.0 --port 8000 <에이전트 디렉터리>
0.0.0.0
을 지정함으로써 모든 네트워크 인터페이스에서 대기하도록 되어 외부에서 서버의 IP 주소에 직접 액세스할 수 있습니다.
- 개발 서버에 SSH 로 로그인
- 서버에서 다음을 실행
adk web --host 0.0.0.0 --port 8000
http://<서버의 IP 주소>:8000
이렇게 하면 원격 환경에서 작동하는 ADK 에이전트를 로컬 브라우저에서 조작할 수 있습니다.
0.0.0.0
로 bind 하면, 동일한 네트워크 상의 호스트뿐만 아니라 방화벽이 열려 있다면 인터넷을 통한 액세스도 가능합니다. 클라우드 환경을 사용할 경우, 보안 그룹이나 방화벽으로 연결원 IP 를 제한하는 것을 강력히 추천합니다.
보안을 걱정할 경우, 0.0.0.0
을 사용하지 않고 SSH 튜널을 사용하는 방법도 있습니다.
ssh -L 8000:localhost:8000 사용자명@<서버의 IP 주소>
이 코맨드를 내 PC 에서 실행한 상태에서 http://localhost:8000
에 액세스하면, SSH 를 통해 원격 서버의 포트에 튜널링됩니다. 통신이 SSH 로 암호화되므로 0.0.0.0
으로 포트를 개방하는 것보다 안전합니다. 상황에 따라 사용하세요.
| 방법 | 장점 | 단점 |
|---|
--host 0.0.0.0 | | |
| 설정이 간편함 | 포트가 외부에 노출됨 | |
| SSH 튜널 | 안전·포트 불필요 | SSH 세션 유지 필요 |
--host 0.0.0.0
을 붙이는 것만으로 간단한 팁이지만, 원격 개발 시에는 지루하게 도움이 되는 옵션입니다.
SSH 튜널과 사용법을 구분하며 편안한 ADK 개발 라이프를 보내세요!
