Gemini API의 Managed Agent: 실습 튜토리얼

Gemini API의 Managed Agent 비용은 얼마인가요?

Gemini Managed Agent의 요금에는 많은 요소가 포함되어 있어 정확한 비용을 추정하기가 어렵습니다. 비용은 크게 네 가지 요인에 의해 결정됩니다:

1. 모델 사용량(토큰): 기반이 되는 Gemini 모델이 처리한 입력 및 출력 토큰 수에 따라 과금됩니다. 중간 결과에서 생성된 토큰도 포함됩니다. 예를 들어, 에이전트가 보고서를 만들기 위해 Python 스크립트를 생성하면, 해당 스크립트에 필요한 토큰도 함께 과금됩니다.
2. 인프라 및 플랫폼 요금: Managed Agent는 Google의 통합 환경에서 실행되며, 에이전트를 관리하고 배포하기 위해 플랫폼 도구(예: Vertex AI Agent Builder)를 사용하는 데 따른 서비스 요금이 발생합니다.
3. 컨텍스트 캐싱: 에이전트가 동일한 데이터를 자주 재사용하는 경우 컨텍스트 캐싱을 활용할 수 있습니다. 이는 일반적인 토큰 요금 대비 의미 있는 비용 절감으로 이어지는 경우가 많습니다.
4. 그라운딩: 에이전트가 Google Search나 Google Maps 같은 Google 그라운드 서비스(Ground services)를 사용하는 경우 별도 과금됩니다. 보통 무료 요청 할당량 이후 1,000건당 비용(대개 약 $14/1,000 쿼리)이 청구됩니다. 

이 튜토리얼에서는 antigravity-preview-05-2026 에이전트를 기반으로 Gemini 3.5 Flash 가 구동하는 에이전트를 구축합니다. Gemini 3.5 Flash의 토큰 비용은 다음과 같습니다:

Gemini API로 Managed Agent를 만드는 방법

이 가이드에서는 Gemini API와 Python을 사용해 Managed Agent를 구축합니다. Managed Agent는 현재 베타 단계의 최신 릴리스이므로, 일부 구현 세부 사항은 변경될 수 있습니다.

이 튜토리얼에서 작성하는 모든 코드는 이 GitHub 저장소에 보관되며, 데이터 분석 에이전트와 데이터를 공유하는 용도로도 사용합니다.

API 설정

AI 키를 만들려면 Google AI Studio로 이동하여 우측 상단의 “Create API Key”를 클릭합니다.

API 키는 Google Cloud 프로젝트와 연결되어야 합니다. 기존 프로젝트를 선택하거나 새로 만들 수 있습니다. 여기서는 gemini-managed-agents라는 프로젝트를 생성했습니다.

키를 만든 뒤 복사합니다. 그런 다음 에이전트를 만들 폴더에 .env라는 파일을 만들고 다음 형식으로 붙여 넣습니다:

GEMINI_API_KEY=<paste_your_api_key_here>

Google AI Studio를 닫기 전에 방금 만든 API 키에 결제를 설정해야 합니다. 이를 설정하지 않으면 Google이 과금할 수 없어 요청이 거부됩니다. 결제를 설정하려면 “Set up billing” 버튼을 클릭하세요.

Python 환경 설정

이 프로젝트의 Python 환경은 Anaconda로 설정하겠습니다. Anaconda로 환경을 만들려면 다음 명령을 사용하세요:

conda create --name gemini_agents python=3.12 -y

이 명령은 Python 3.10 버전을 사용하는 gemini_agents라는 환경을 생성합니다. -y 매개변수는 환경 생성 중 묻는 질문에 모두 “예”로 자동 응답하는 바로가기입니다.

다음으로 환경을 활성화합니다:

conda activate gemini_agents

마지막으로 필요한 종속 항목을 설치합니다. 방법은 다음과 같습니다:

pip install google-genai requests python-dotenv

Managed Agent와의 기본 상호작용 만들기

이제 첫 번째 에이전트를 실행할 모든 준비가 끝났습니다. 이 첫 에이전트는 많은 일을 하지는 않습니다. matplotlib를 설치하고 설치된 버전을 보고하는 정도입니다.

Managed Agent와 상호작용하는 방법을 단계별로 설명합니다(전체 코드는 저장소의 simple_interaction.py 스크립트에서 확인할 수 있습니다):

먼저 필요한 패키지를 임포트하고, 앞서 만든 .env 파일에서 API 키를 불러옵니다:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

다음으로 Gemini 클라이언트를 초기화하고 기본 에이전트(antigravity-preview-05-2026)에 matplotlib 설치를 요청하는 상호작용을 생성합니다:

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

마지막으로 status, environment_id, output_text 속성을 확인해 에이전트 출력을 가져옵니다:

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

결과는 다음과 같습니다:

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

샌드박스 수명 주기 상태

위 예시에서 Managed Agent 상호작용의 환경 식별자를 출력했습니다:

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

이 값은 에이전트가 실행된 환경의 식별자를 의미하므로 중요합니다. 에이전트 상호작용은 마지막 활동 이후 최대 7일 동안 유지되는 휘발성 환경에 저장되며, 이후 삭제됩니다.

아래 다이어그램은 상호작용 중 에이전트가 실행되는 샌드박스의 수명 주기를 보여 줍니다.

환경이 삭제되지 않았다면 환경 식별자를 사용해 접근하고 추가 상호작용을 수행할 수 있습니다.

여러 번의 상호작용 수행

이 예시에서는 여러 번의 상호작용을 수행하는 방법을 보여 줍니다. 전체 코드는 저장소의 multiple_interactions.py 파일에서 확인할 수 있습니다.

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

두 번째 상호작용에서 두 개의 매개변수를 추가한 점에 유의하세요:

• previous_interaction_id: 이전 상호작용의 식별자입니다. 에이전트가 대화 이력을 인지할 수 있도록 합니다.

• environment: 에이전트가 어떤 샌드박스에서 실행해야 하는지 알 수 있도록 환경 식별자를 제공합니다.

에이전트와 파일 공유하기

데이터에 접근하지 못하면 데이터 분석 에이전트를 만들 수 없습니다. 에이전트와 데이터를 공유하는 방법은 몇 가지가 있습니다:

• 인라인 데이터: 파일 내용을 문자열로 로드해 상호작용 중에 전송합니다.
• 호스팅 파일: 데이터를 공개 URL에 호스팅하고, 에이전트가 다운로드할 수 있도록 URL을 제공합니다.
• GitHub 저장소: 에이전트에 공개 GitHub 저장소 URL을 제공합니다.
• Google Cloud 버킷: 파일을 Google Cloud Storage 버킷에 호스팅하고, 에이전트가 해당 버킷에 접근할 수 있도록 프로젝트를 구성합니다.

이 글에서는 모든 방법을 다루지는 않습니다. 로컬 파일을 문자열로 로드해 인라인 데이터로 보내는 방법과 GitHub 저장소를 공유하는 방법을 보여 드립니다. 전자는 작은 로컬 파일(파일당 최대 1MB, 전체 파일 합계 2MB 한도)에 적합하고, 후자는 데이터셋 같은 큰 파일을 공유할 때 더 적합합니다.

인라인 데이터 공유

인라인 데이터를 제공하는 예시는 다음과 같습니다(전체 코드는 inline_example.py에 있음):

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

데이터는 environment 구성의 sources 매개변수를 사용해 제공합니다. target은 데이터가 에이전트 환경의 어디에 저장될지를 정의합니다. 파일은 workspace 폴더에 위치해야 합니다. 이 경우 number.txt라는 파일이 됩니다. 

content 매개변수는 파일 내용을 제공합니다. inline 소스에서는 단순히 문자열이며, 여기서는 utils.py 파일의 read_text_file() 함수를 사용해 읽습니다.

GitHub 저장소 공유

더 큰 파일을 공유하려면 GitHub 저장소 URL을 제공할 수 있습니다. 방법은 다음과 같습니다:

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

위 예시에서는 URL https://github.com/fran-aubry/gemini-agents-tutorial의 저장소를 에이전트 작업 공간 내부의 repository라는 폴더로 클론합니다.

에이전트 환경 다운로드

이제 Managed Agent와 상호작용하는 방법과 에이전트에 파일을 제공하는 방법을 배웠습니다. 데이터 분석 에이전트를 만들려면 마지막으로 에이전트의 환경을 다운로드하는 방법을 알아야 합니다. 이는 에이전트가 생성한 차트와 결과에 접근하기 위해 필요합니다.

각 작업 공간은 다음 URL에서 다운로드할 수 있습니다:

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

여기서 <env_id>는 다운로드하려는 환경의 식별자로 바꿔야 합니다.

아래는 requests 패키지를 사용해 패키지를 다운로드하는 Python 함수입니다(이 함수는 우리가 만든 utils.py 파일의 일부입니다):

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

데이터 분석 에이전트 구축

이 섹션에서는 데이터 분석을 수행하는 에이전트를 만드는 방법을 알아봅니다. 에이전트를 테스트하기 위해 Kaggle에서 가져온 이 Netflix 데이터셋을 사용하며, data 폴더에도 저장되어 있습니다.

이전 예시에서는 항상 기본 에이전트인 antigravity-preview-05-2026와 상호작용했습니다. 여기서는 먼저 client.agents.create() 함수를 사용해 에이전트를 생성하겠습니다.

에이전트 생성

에이전트를 생성하는 방법은 다음과 같습니다:

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

각 매개변수를 살펴보겠습니다:

• id: 에이전트의 이름을 정의합니다. 여기서는 data-analyst입니다. 이제까지 사용하던 antigravity-preview-05-2026 대신 이 식별자를 client.interactions.create() 메서드에 사용합니다. 

• base_agent: 기반으로 사용할 에이전트입니다. 즉, antigravity-preview-05-2026 에이전트 위에 새로운 에이전트를 구축합니다.

• base_environment: 앞서와 같이 에이전트에 파일을 제공할 수 있습니다. 여기서는 .agents/AGENTS.md와 .agents/skills/csv-aggregator/SKILL.md라는 두 개의 특수 파일을 제공했습니다. 이 파일들은 에이전트의 동작을 정의하는 곳입니다. AGENTS.md는 에이전트의 일반적인 동작을, SKILL.md는 특정 스킬을 정의합니다. 또한 데이터 파일에 접근할 수 있도록 저장소도 제공했습니다.

AGENTS.md 이해하기

이 파일은 시스템 프롬프트로 생각할 수 있습니다. 에이전트를 위한 기본 사용 설명서 역할을 합니다. 에이전트의 구체적인 역할, 주요 목표, 작업 중 준수해야 할 한계를 명확히 정의하는 데 사용해야 합니다. 

또한 에이전트가 접근할 수 있는 특정 도구나 데이터 소스를 나열하고, 원하는 커뮤니케이션 방식이나 작업 처리 예시를 제공하기에 가장 좋은 위치입니다. 

이 지침을 파일 내에 간결하고 체계적으로 유지하면, 에이전트가 정확히 어떻게 행동해야 하는지와 우리가 기대하는 결과를 이해하는 데 도움이 됩니다.

파일의 위치는 에이전트 환경에서 .agents/AGENTS.md여야 합니다.

SKILL.md 이해하기

스킬 파일은 에이전트에 특정 능력을 부여하는 데 사용됩니다. 에이전트는 여러 스킬을 가질 수 있으며, 각 스킬은 .agents/skills/<skill_name>/SKILL.md에 위치한 SKILL.md 파일로 설명해야 합니다. <skill_name>은 스킬 이름으로 바꿉니다.

스킬 파일의 구조는 다음과 같아야 합니다:

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

예시로, 우리는 data-analyst 에이전트에 csv-aggregator라는 스킬을 장착했으며, 정의는 여기에 있습니다. 이 스킬은 어떤 열로 CSV의 행을 그룹화하고 다른 열을 합산해야 할 때 사용됩니다. 

Netflix 데이터셋의 경우, 조회 수가 가장 많은 장르를 알고 싶다면 Genre로 행을 그룹화하고 Viewership 열의 값을 합산하면 됩니다. 이 스킬 파일은 해당 작업을 수행하는 방법을 에이전트에 설명합니다.

에이전트 로드

에이전트는 지속되므로, 에이전트 생성을 두 번 실행하면 오류가 발생합니다. 이를 피하기 위해 utils.py 파일에 load_or_create_agent() 함수를 만들었습니다. 이 함수는 에이전트 생성을 시도하고, 이미 존재하면 client.agents.load() 함수를 사용해 대신 로드합니다.

모두 합쳐 보기

이제 데이터 분석 에이전트가 준비되었으니, Netflix 장르를 분석하도록 요청해 시험해 보겠습니다. 

먼저 라이브러리를 임포트하고, API 키를 로드한 뒤, 클라이언트를 초기화합니다:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

그다음 utils.load_or_create_agent() 함수를 사용해 data-analyst 에이전트를 생성(또는 스크립트를 처음 실행하는 것이 아니라면 로드)합니다:

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

그다음은 이전과 동일한 방식으로 에이전트와 상호작용할 수 있습니다. 다른 점은 agent 매개변수에 이제 antigravity-preview-05-2026 대신 우리가 만든 에이전트를 제공한다는 것입니다.

먼저 에이전트에게 matplotlib 패키지를 설치하라고 요청합니다:

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

이전에 환경을 에이전트 수준에서 이미 구성했으므로 더 이상 파일을 제공할 필요가 없으며, 단지 문자열 ”remote”만 제공하면 됩니다.

다음으로 csv-aggregator 도구를 사용해 Netflix 데이터를 장르별로 분석하여 가장 많이 시청된 장르를 확인하도록 요청합니다:

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

에이전트가 그 위에서 계속 작업할 수 있도록 이전 상호작용의 환경 식별자를 제공한다는 점에 유의하세요.

마지막으로, 이전 단계에서 생성된 genres.py 스크립트를 실행해 데이터를 시각화하도록 요청합니다(SKILL.md 파일이 이 스크립트를 생성하도록 지시합니다):

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

이 상호작용 이후에 플롯이 생성됩니다. 환경을 다운로드해 로컬로 가져올 수 있습니다:

utils.download_env(inter3.environment_id)

결과는 다음과 같습니다:

에이전트 상호작용의 전체 코드는 analyze_netflix_genres.py에서 확인할 수 있습니다.

결론

복잡한 클라우드 컴퓨팅 인프라 없이 한 번의 API 호출만으로 복잡한 에이전트를 만들 수 있다는 점은 매우 강력합니다. 이 기능 덕분에 에이전트가 실행되는 환경을 걱정하지 않고도 강력한 에이전트를 손쉽게 만들 수 있습니다.

이 튜토리얼에서는 Gemini Managed Agent의 기초를 다뤘지만, 정말 복잡한 에이전트를 만들지는 않았습니다. 이 기초 위에 계속해서 빌드하며 더 깊이 탐구해 역량을 강화해 보시기 바랍니다.