Credentials API에 시크릿을 한 번만 저장하고 ID로 참조해 두면, 이그레스 프록시가 전송 과정에서 자동으로 주입하기 때문에 에이전트 샌드박스에는 시크릿이 노출되지 않습니다.
최근 매니지드 에이전트(antigravity-preview-09-2026)에 Credentials API가 출시되었습니다. 이 API를 활용하면 에이전트가 GitHub, Notion, Gemini API 같은 외부 서비스에 인증할 때 리눅스 샌드박스 안에 시크릿을 직접 노출하지 않아도 됩니다.

API 키를 일반 환경 변수로 전달하면 샌드박스 내부의 어떤 의존성이나 스크립트도 os.environ를 읽어 유출할 수 있습니다. Credentials API를 사용하면 시크릿은 서버에 보관되고, 이그레스 프록시가 전송 과정에서 자동으로 주입합니다.
credentials.create()으로 크리덴셜을 등록합니다. 시크릿은 쓰기 전용이며 저장 시 암호화되고, API 응답에는 메타데이터(id, type, status, 타임스탬프)만 반환됩니다.

크리덴셜 유형은 3가지입니다:
bearer_token: HTTP 헤더로 주입되는 정적 토큰 및 API 키(기본값은 Authorization: Bearer <token>, 또는 header_name와 prefix를 직접 지정 가능).oauth2: 리프레시 토큰(client_id, client_secret, refresh_token, token_url). Gemini가 만료 전에 액세스 토큰을 자동으로 교환하고 갱신합니다.environment_variable: 프로세스 환경에서 시크릿을 읽는 CLI 및 SDK용. 컨테이너에는 플레이스홀더(__GEMINI_CRED_<id>__)가 전달되고, 이그레스 프록시가 trusted_domains로의 요청에 한해 실제 값으로 교체합니다.agents.create()으로 재사용 가능한 에이전트를 정의하거나(또는 interactions.create()에서 실행 단위로 지정), 원격 mcp_server 도구, network.allowlist의 도메인, 또는 base_environment.env의 변수에 크리덴셜 id를 지정합니다.

에이전트가 MCP 도구를 호출하거나 샌드박스에서 외부로 HTTP 요청을 보낼 때, 이그레스 프록시가 대상 도메인을 확인하고 전송 과정에서 실제 크리덴셜을 주입합니다.

다음은 GitHub MCP 서버를 통해 google-gemini/cookbook를 관리하고 안전하게 Gemini API를 호출할 수 있는 재사용 가능한 커스텀 에이전트의 실제 예제입니다. GEMINI_API_KEY이 크리덴셜로 바인딩되어 있어, 샌드박스 내 신뢰할 수 없는 코드도 실제 API 키를 보지 않고 generativelanguage.googleapis.com을 호출할 수 있습니다.

GITHUB_PAT와 GEMINI_API_KEY를 내보냅니다.SDK(bun add @google/genai)를 설치하고 다음을 실행합니다:
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
// 1. Store credentials once
const github = await ai.credentials.create({
id: "github-mcp",
type: "bearer_token",
token: process.env.GITHUB_PAT!,
});
const geminiKey = await ai.credentials.create({
id: "gemini-key",
type: "environment_variable",
value: process.env.GEMINI_API_KEY!,
injection_location: ["header", "query"],
trusted_domains: ["generativelanguage.googleapis.com"],
});
// 2. Define a reusable agent wired to both credentials
const agent = await ai.agents.create({
id: "cookbook-pr-reviewer",
base_agent: "antigravity-preview-09-2026",
system_instruction:
"You are a maintainer for google-gemini/cookbook. Use the github tools to inspect pull requests, and use the sandbox to smoke-test Gemini API snippets and draft release notes.",
tools: [
{ type: "code_execution" },
{
type: "mcp_server",
name: "github",
url: "https://api.githubcopilot.com/mcp/",
credential: github.id,
},
],
base_environment: {
type: "remote",
env: {
GEMINI_API_KEY: { credential: geminiKey.id },
},
},
});
// 3. Run the agent
const interaction = await ai.interactions.create(
{
agent: agent.id,
environment: "remote",
input:
"Draft a release note for the 3 most recently merged PRs in google-gemini/cookbook, and run a live smoke test against gemini-3.8-flash in the sandbox to verify the code snippet works.",
},
{ timeout: 300000 },
);
console.log(interaction.output_text);출력 결과:
# Release Notes: `google-gemini/cookbook`
### 1. [PR #1347](https://github.com/google-gemini/cookbook/pull/1347) - Zero-Cloud Local Hybrid RAG Recipe with SQLite FTS5 & Gemini
- **Author:** @Cagrik34 | **Merged At:** 2026-09-28 10:49:52 UTC
- **Summary:** Combines SQLite FTS5 (`unicode61`) BM25 search with `text-embedding-004` dense vectors and Reciprocal Rank Fusion (RRF, k=60) in `examples/Zero_Cloud_Hybrid_RAG_SQLite_FTS5_Gemini.ipynb`.
### 2. [PR #1383](https://github.com/google-gemini/cookbook/pull/1383) - Fix `musicGenerationConfig` Schema in Lyria RealTime Notebook
- **Author:** @kkorpal | **Merged At:** 2026-09-28 10:29:00 UTC
- **Summary:** Updates `music_generation_config` to `musicGenerationConfig` and flattens the payload in `quickstarts/Get_started_LyriaRealTime.ipynb`.
### 3. [PR #1384](https://github.com/google-gemini/cookbook/pull/1384) - Fix HTTP 400 BadRequest via File API in Prompting Notebook
- **Author:** @kkorpal | **Merged At:** 2026-09-25 12:29:48 UTC
- **Summary:** Switches multimodal image upload in `quickstarts/Prompting.ipynb` to `client.files.upload`.실행 중 일어나는 일:
github-mcp): api.githubcopilot.com/mcp/에 연결해 github:list_pull_requests와 github:pull_request_read을 호출하고, 최근 병합된 PR(#1347, #1383, #1384)을 검사합니다.gemini-key): 컨테이너 내부에서 $GEMINI_API_KEY는 __GEMINI_CRED_gemini-key__입니다. 스모크 테스트가 generativelanguage.googleapis.com를 호출하면, 이그레스 프록시가 전송 과정에서 플레이스홀더를 실제 키로 교체합니다.__GEMINI_CRED_gemini-key__를 포함한 요청이 trusted_domains 외부 도메인으로 전송되면 차단됩니다(403).에이전트 정의를 변경하지 않고도 ID로 크리덴셜을 업데이트해 시크릿을 교체하거나, 더 이상 필요하지 않을 때 삭제할 수 있습니다:
await ai.credentials.update("github-mcp", {
type: "bearer_token",
token: process.env.GITHUB_PAT_NEW!,
});
await ai.credentials.delete("github-mcp");
await ai.credentials.delete("gemini-key");자세한 내용은 Credentials API 문서, 커스텀 에이전트 가이드, 매니지드 에이전트 빠른 시작을 참고하세요.
읽어주셔서 감사합니다! 질문이나 피드백이 있으시면 Twitter나 LinkedIn으로 알려주세요.