AI Studio Playground의 에이전트

AI Studio Playground의 에이전트

Google AI Studio Playground는 API 호출을 직접 만들고 작성하지 않고도 관리형 에이전트(managed agents)를 프로토타이핑하고 배우는 방법을 제공하는 시각적 인터페이스예요.

시작하려면 Google AI Studio의 내비게이션 패널에서 Playground 탭으로 이동하고 토글을 Agents로 전환하세요.

출처: 원문

본문

사전 구축 템플릿(Pre-built templates)

Agents 탭에는 도구와 환경 구성을 설정해서 기본 Antigravity Agent를 사전 구성하는 일련의 템플릿이 있어요. 모든 템플릿은 오픈소스이며 google-gemini/gemini-managed-agents-templates 저장소에 게시돼 있어요. 이 템플릿을 살펴보는 것은 자신만의 관리형 에이전트를 만들고 구성하는 방법을 배우는 좋은 방법이에요.

예를 들어 AI Radio 템플릿을 선택하면 모든 허용 도구가 활성화되고 라디오 쇼 제작을 위한 전용 AGENTS.md 파일과 스킬이 연결돼요. 이러한 설정은 Playground UI의 Environment 섹션에서 Sources 버튼을 클릭하면 볼 수 있어요.

중요: 이 템플릿을 실행하면 샌드박스 안의 에이전트가 Gemini API에 접근할 수 있어요. 구성된 API 키를 사용해 호출을 실행하며, 이는 계정에 추가 토큰 요금이 발생할 수 있어요. 자세한 내용은 안전 및 비용 관리 섹션을 참고하세요.

도구 구성(Tool configuration)

Playground의 에이전트 설정에서 다음 내장 도구에 대한 접근을 토글할 수 있어요:

• Google Search: 실시간 정보 grounding을 위해 공개 웹에 접근해요.
• URL Context: 특정 웹 페이지 URL의 텍스트 콘텐츠를 가져와 파싱해요.
• Code Execution: 격리된 샌드박스 환경 안에서 Bash와 Python 명령을 직접 실행해요.
• Filesystem Tools: 작업 공간 안의 파일을 읽기, 쓰기, 나열, 삭제해요.

환경 구성(Environment Configuration)

관리형 에이전트는 작업에 필요한 작업 공간과 도구를 제공하는 안전한 일시적(ephemeral) Linux 샌드박스(환경) 안에서 실행돼요. 자세한 내용은 관리형 에이전트 환경 가이드를 참고하세요.

에이전트 동작 제어

에이전트의 동작, 페르소나, 기능은 주로 환경에 존재하는 파일에 의해 결정돼요. 에이전트는 특별한 .agents 폴더에서 구성을 자동으로 감지하고 로드해요:

• AGENTS.md: 시스템 지침과 페르소나를 정의하기 위해 에이전트의 컨텍스트에 미리 로드돼요.
• SKILL.md: 특정 기능과 워크플로를 정의하기 위해 각 스킬 폴더 아래(예: .agents/skills/my-skill/SKILL.md)에 위치해요.

환경 프로비저닝

세션을 시작하기 전에 환경에 파일을 마운트해서 에이전트가 사용할 환경을 구성할 수 있어요. 소스를 마운트해 새 환경을 만들거나 이전 환경을 복원할 수 있어요:

• 새 환경을 만들려면: Environment 설정 패널에서 Add Sources를 클릭하고 다음 소스 유형 중 하나를 선택해요:

소스 유형	설명	마운트 경로
Inline Files	구성 파일, 목 데이터셋, 유틸리티 스크립트(최대 100KB)를 Playground UI에 직접 쓰거나 붙여넣어요.	사용자 정의 대상 경로(예: /workspace/scripts/parser.py).
Google Cloud Storage	공개 또는 비공개 Cloud Storage 버킷을 마운트해요. 비공개 버킷은 표준 OAuth 2.0 Bearer 토큰이 필요해요. 자세한 내용은 Private sources를 참고하세요.	GCS 버킷 경로(예: gs://your-bucket-name/data/)를 작업 공간 디렉터리(예: /workspace/data/)에 매핑해요.
GitHub Repositories	공개 또는 비공개 코드베이스를 클론해요. 비공개 저장소는 GitHub Personal Access Token(PAT)으로 Basic 인증이 필요해요. 자세한 내용은 Private sources를 참고하세요.	/workspace/에 직접 클론돼요(보통 /workspace/<repo-name> 아래).

• 이전 환경을 복원하려면: 기존 환경 ID 재사용으로 정확한 상태를 복제하고 포크할 수 있어요.

기존 환경 ID 재사용

이미 샌드박스 환경을 설정하는 데 시간을 썼다면 처음부터 다시 시작할 필요가 없어요. 기존 환경을 사용하려면:

1. AI Studio의 Environments 패널로 가서 Type을 Existing으로 토글해요.
2. Environment ID(예: env_abc123)를 입력해요.

자세한 내용은 환경 구성하기를 참고하세요. UI의 Environment 탭에서 현재 세션의 Environment ID를 가져올 수도 있어요.

에이전트에게 첫 메시지를 보내면 해당 세션의 환경 구성이 고정돼요. 상호작용이 활발히 실행되는 동안에는 새 소스를 마운트하거나 네트워크 허용 목록을 수정할 수 없어요.

환경 다운로드하기

환경이 생성된 후에는 AI Studio Playground의 환경 설정에 있는 Download 버튼을 사용해 언제든지 환경 스냅샷을 다운로드할 수 있어요. 환경 파일을 tarball로 가져올 수 있어요.

안전 및 비용 관리(Safety and Cost Management)

토큰 소비 관리

단일 출력을 생성하는 표준 채팅 요청과 달리, Antigravity Agent는 자율 워크플로를 실행해요. 계획을 세우고, 코드를 실행하고, 결과를 관찰하고, 반복해요. 즉, 단일 프롬프트가 무한정한 토큰 소비로 이어질 수 있어요.

비용을 관리하려면 프롬프트에 명확한 종료 기준을 제공하고 작업 범위를 좁게 설정하세요. 좋은 예는 "풀 리퀘스트를 검토하고 마크다운 요약을 생성하면 멈춰줘. 수정을 직접 시도하지 마" 같은 프롬프트예요.

중요: 에이전트가 오래 실행되거나 올바른 방향으로 가지 않는 것 같으면(생각과 도구 호출을 관찰해서 알 수 있어요) Stop 버튼을 사용해 언제든지 에이전트를 멈추고 불필요한 토큰 소비를 피할 수 있어요.

추가 비용

기본적으로 Playground의 모든 에이전트 템플릿은 Gemini API 서비스에 접근할 수 있고 요청을 수행하기 위해 환경에서 API 호출을 할 수 있어요. 이는 토큰 소비에 반영되지 않는 추가 비용이 발생할 수 있어요.

마찬가지로 다른 외부 서비스를 추가하면 에이전트가 사용자를 대신해 이 서비스를 호출함으로써 추가 비용이 발생할 수 있어요.

네트워크 허용 목록(Network Allow List)

기본적으로 AI Studio에서는 에이전트 샌드박스 환경 내부의 모든 아웃바운드 네트워크 요청이 보안을 위해 엄격하게 통제되고 제한돼요. 에이전트가 외부 API, 웹 서비스, 패키지 관리자에 도달할 수 있게 하려면 이를 명시적으로 선언해야 해요:

1. AI Studio의 Environments 패널로 가요.
2. Network 옆의 rules 버튼을 선택해요.
3. Network configuration 패널에서 Add to allowlist를 클릭하고 관련 세부 정보를 입력해요:

도메인 제한: 목록에 추가된 특정 도메인 또는 와일드카드 패턴만 에이전트의 가상 머신이 접근할 수 있어요. 예를 들어 api.github.com 같은 정확한 도메인이나 *.googleapis.com 같은 광범위한 패턴을 입력할 수 있어요.

HTTP 헤더·토큰 주입 추가: Add HTTP header 옵션을 사용해 특정 도메인에 필요한 자격 증명(예: API 토큰)을 안전하게 주입해요. 이 자격 증명은 이그레스 프록시를 통해 안전하게 전달되며 에이전트 샌드박스 안에 원시 텍스트로 직접 노출되지 않아요.

허용 목록에 도메인을 추가할 때는 항상 주의하세요. 인증된 서비스에 에이전트 접근을 부여하면 에이전트가 사용자를 대신해 행동할 수 있고, 신중히 모니터링하지 않으면 의도하지 않은 작업으로 이어질 수 있어요.

중요:

• AI Studio Playground를 통한 모든 에이전트 호출에는 인증된 Gemini API(연결된 API 키 사용)가 기본적으로 활성화돼 있어요.
• API를 사용할 때는 네트워크가 기본적으로 열려 있어요. 자세한 내용은 API 문서를 참고하세요.

자격 증명 모범 사례

워크플로가 에이전트가 외부 서비스에 인증해야 한다면 자격 증명을 프로비저닝하고 범위를 지정하는 책임은 사용자에게 있어요. 위험을 줄이기 위해 다음 지침을 따르세요:

• 최소 권한 자격 증명 사용: 에이전트가 필요한 권한만 있는 서비스 계정이나 API 키를 만들어요. 광범위하거나 관리자 접근 권한이 있는 자격 증명을 전달하지 마세요.
• 단기 토큰 선호: 가능하면 오래 지속되는 API 키보다 만료되는 시간 제한 자격 증명이나 토큰을 사용해요.
• 전체 접근 가정: 에이전트는 주어진 작업을 완료하기 위해 접근할 수 있는 모든 자격 증명을 사용할 수 있어요. 기꺼이 부여할 전체 접근 범위의 자격 증명만 제공하세요.
• 자격 증명 정기 회전: 에이전트와 공유한 자격 증명을 다른 프로그래밍 방식 자격 증명과 동일하게 취급하고 정기적으로 회전하세요.

외부 도구와 API 연결

에이전트의 기능을 확장하기 위해 외부 도구와 API(예: Model Context Protocol / MCP 서버)를 연결할 수 있어요. 이때:

• 신뢰하는 소스의 도구만 연결하세요. 악의적이거나 제대로 작성되지 않은 도구는 데이터를 노출하거나 의도하지 않은 작업을 수행할 수 있어요.
• 사용 사례에 필요한 최소 권한으로 도구를 구성하세요. 도구가 읽기 전용 모드를 지원하면 쓰기가 꼭 필요하지 않는 한 그 모드를 선호하세요.
• 도구를 프로덕션 데이터 소스에 연결하기 전에 샘플 또는 합성 데이터로 테스트해서 에이전트가 예상대로 사용하는지 확인하세요.

인간 감독(Human oversight)

에이전트는 높은 수준의 자율성으로 다단계 워크플로를 추론하고 계획하고 실행할 수 있어요. 강력하기는 하지만, 특히 데이터를 수정하거나 외부 시스템과 상호작용하는 작업에는 적절한 감독을 적용해야 한다는 뜻이기도 해요.

생성된 코드, 데이터 변환, 구성 변경 같은 중요한 출력은 배포 전에 항상 검증하세요.

더 알아보기 (Learn more)

• 관리형 에이전트 환경
• gemini-managed-agents-templates 저장소