안녕하세요!

KDDI 아이렛(KDDI iret)의 활동으로서 6월 22일~7월 3일 기간 동안 개최 중인 「Google Cloud Next '26 / Google I/O 해본 계열 블로그 릴레이」, 오늘은 9일째 포스팅입니다.

이번에는 「Managed Agents API」를 대상으로, 실제로 검증해 본 모습을 전달해 드립니다!

이전 기사는 여기 있습니다.

AI 에이전트 시스템을 구축하려고 하면, 안전한 실행 환경(Sandbox, 샌드박스) 확보나 외부 API·데이터와의 보안 연동 등 인프라 측면의 설계에 많은 공수가 들기 마련입니다.

이러한 과제를 해결하는 수단으로서, Google I/O 2026에서 「Managed Agents API」가 발표되었습니다.

이는 개발자가 번거로운 인프라나 샌드박스 환경을 관리할 필요 없이, API를 호출하는 것만으로 자율적으로 동작하는 에이전트를 구축할 수 있는 기능입니다.

이 API의 특징은 1회의 호출로 「컨트롤 플레인 (Control Plane)」과 「데이터 플레인 (Data Plane)」 두 가지를 연계하여, 보안이 확보된 자율형 에이전트 실행 환경(Sandbox)을 즉시 프로비저닝(Provisioning)할 수 있다는 점에 있습니다.

API	역할	주요 기능·설명
Agents API	컨트롤 플레인 (Control Plane)	에이전트의 구성 관리, 외부 데이터 소스 마운트, 네트워크 허용 목록(Allowlist) 설정 등 실행 환경의 제어를 수행합니다.
Interactions API	데이터 플레인 (Data Plane)	배포된 에이전트와 실시간으로 통신하며 조작을 수행하기 위한 주요 인터페이스입니다.

이렇게 2개 층으로 나뉘어 있는 것은 보안상의 이유가 있습니다.

컨트롤 플레인(Agents API)은 에이전트의 「설정·구성 정보」만을 관리하며, 실제 데이터 교환과는 완전히 분리되어 있습니다.

이를 통해 실행 시의 데이터가 에이전트의 설정에 간섭하거나 외부로 유출될 리스크를 구조적으로 배제합니다.

또한, 네트워크 액세스는 기본적으로 꺼져 있으며, allowlist에 명시된 도메인만 통신할 수 있도록 설계되어 있습니다.

에이전트의 실행 기반에는 Antigravity(base_agent="antigravity-preview-05-2026")라고 불리는 오케스트레이션 하네스(Orchestration Harness)가 사용됩니다.

Antigravity의 주요 역할은 다음과 같습니다.

• 추론과 계획

• Gemini 모델을 기반으로 사용자의 지시를 어떤 절차로 실행할지 추론합니다.

• 도구 호출 (Tool Call)

• code_execution (코드 실행)이나 url_context (URL 참조)와 같은 도구를 자율적으로 호출합니다.

• 스킬 로드

• /.agent/skills에 배치된 SKILL.md를 자동 검색·해석하여 정의된 동작을 따릅니다.

에이전트의 실행 환경은 인터랙션마다 에페머럴(Ephemeral, 일시적)한 Linux 환경으로서 기동됩니다.

이 샌드박스의 특징은 다음과 같습니다.

• 인터랙션이 완료되면 환경은 파기되며 상태가 유지되지 않음
• GCS 버킷이나 Skill Registry를 마운트함으로써 파일이나 스킬을 주입할 수 있음
• 코드 실행 및 파일 조작은 모두 이 격리된 환경 내에서 이루어짐

개발자는 이 샌드박스 환경의 구축·관리를 전혀 의식하지 않고, API를 호출하는 것만으로 즉시 보안이 확보된 에이전트 실행 환경을 얻을 수 있습니다.

그래서 본 기사에서는 실제로 Managed Agents API를 사용하여 에이전트를 구축하고, 그 동작을 테스트해 보았습니다!

pip install google-genai>=2.0.0

• tools

• 에이전트에게 부여할 도구 (Tool)

• system_instruction

• 에이전트에게 설정하는 시스템 지시 또는 페르소나

• sources의 gcs

• 마운트할 GCS

• network

• 기본적으로 보안상의 이유로 환경 내의 네트워크 액세스는 꺼져 있음

• 액세스를 활성화하려면 allowlist를 지정해야 함 - 운영 환경에서는 특정 도메인만 허용할 것

이번에는 GCS에 AgentSkill 정의 파일을 저장하고, 그 스킬을 설정하고 있습니다.

간단하게 사용자가 인사를 하면, 「기분은 어때?」라고 반환하는 스킬을 정의하고 있습니다.

---
name: greeting
description: 사용자로부터의 인사말에 응답하는 스킬
...

from google import genai
PROJECT_ID = "your-project"
AGENT_ID = "agent-name"
...

from google import genai
PROJECT_ID = "your-project"
AGENT_ID = "agent-name"
...

설정된 에이전트의 정보를 확인할 수 있습니다.

id='agent-name' base_agent='antigravity-preview-05-2026' system_instruction='당신은 사용자를 지원하는 에이전트입니다.' description='테스트용 에이전트' tools=[CodeExecution(type='code_execution'), URLContext(type='url_context')] base_environment=Environment(type='remote', sources=[Source(type='gcs', source='gs://your-bucket/greeting', target='/.agent/skills', content=None, encoding=None)], network=Allowlist(allowlist=[AllowlistEntry(domain='*', transform=None)])) name='projects/your-project/locations/global/agents/agent-name' created='2026-06-27T07:25:24.913Z' updated='2026-06-27T07:25:27.683Z' object='agent'

생성한 AGENT_ID를 지정하여 지시합니다.

from google import genai
PROJECT_ID = "your-project"
AGENT_ID = "agent-name"
...

다음과 같은 답변이 반환됩니다.

stream=True
덕분에 응답은 Server-Sent Events (SSE) 형식으로 전송됩니다.

interaction=InteractionSseEventInteraction(id=...) event_type='interaction.created' event_id=None metadata=None
interaction_id=... status='in_progress' event_type='interaction.status_update' event_id=None metadata=None
index=0 step=FunctionCallStep(name='list_dir', arguments={}, id=..., type='function_call') event_type='step.start' event_id=None metadata=None
...

안녕하세요! 기분은 어때?

| 단계 | 에이전트의 행동 | 로그의 해당 부분 |
|---|---|---|
| Step 1: 스킬 검색 | 이용 가능한 스킬(기능)이 저장된 디렉토리를 확인한다 | `list_dir` `(index=0, 1)` |
| Step 2: 규칙 확인 | 발견한 스킬 상세 파일(`SKILL.md`)의 내용을 읽어온다 | `view_file` `(index=2, 3)` |
| Step 3: 응답 출력 | 파일의 지시에 따라 사용자에게 전달할 답변 텍스트를 생성 및 출력한다 | `ModelOutputStep` `(index=4)` |
| Step 4: 처리 완료 | 일련의 상호작용(Interaction)을 완료하고, 사용된 토큰 수 등의 통계 정보를 기록한다 | `interaction.completed` |

from google import genai
PROJECT_ID = "your-project"
AGENT_ID = "agent-name"
...

Google I/O 2026에서 발표된 「Managed Agents API」를 검증해 보았습니다!

실제로 사용해 보니 그 "간편함"을 알 수 있었습니다.

인프라의 뒷단(Back-end)을 의식하지 않고, GCS의 스킬 파일을 마운트하여 즉시 자율적인 에이전트가 작동하는 경험은 앞으로의 AI 애플리케이션 개발의 표준이 될 것 같다는 예감이 듭니다.

로그의 타임라인을 따라가는 것만으로도 에이전트가 "디렉토리를 확인하고", "파일을 읽고", "지시대로 답변하는" 단계를 밟고 있다는 것을 볼 수 있어, 내부 동작을 확인할 수 있었습니다.

이번에는 단순한 인사 스킬이었지만, 이를 베이스로 하여 다양한 에이전트를 쉽게 만들어낼 수 있을 것 같다는 느낌을 받았습니다!