지연 등급을 사용하여 Gemini Enterprise Agent Platform에서 할인된 요금으로 커스텀 에이전트에 대한 비동기 멀티턴 Gemini 모델 호출을 실행합니다. Interactions API에서 Agent Platform은 24시간 목표 내에서 백그라운드 실행을 위해 지연된 각 차례를 큐에 추가하고 7일 동안 상태를 유지합니다.
지연 등급은 다음과 같이 차례별 제어가 필요한 지연 허용 에이전트 워크로드에 적합합니다.
- 다단계 코딩 및 보안 에이전트: 저장소 취약점 스캔, 자동화된 코드 마이그레이션, 회귀 분류
- 문서 및 연구 파이프라인: 기술 설계 검토, 재무 백테스팅, 도구 호출을 통한 다중 문서 합성
- 오프라인 에이전트 평가: 실시간 지연 시간 제약 조건 없이
previous_interaction_id대화를 연결하는 대규모 품질 벤치마크입니다.
모든 컴퓨팅 모델을 비교하려면 소비 옵션을 참조하세요. Gemini Deep Research 에이전트에서 에이전트 개발 키트(ADK) 에이전트 또는 관리형 실행을 예약하려면 자율 에이전트 예약을 참조하세요.
지원되는 모델 및 위치
지연 등급은 global 엔드포인트(aiplatform.googleapis.com의 locations/global)에서만 지원됩니다. service_tier="deferred"가 포함된 요청을 리전 엔드포인트 또는 us 또는 eu 멀티 리전 엔드포인트로 전송하면 HTTP 400("code": "invalid_request")가 반환됩니다.
다음 주요 Gemini 모델은 global 엔드포인트에서 지연 등급을 지원합니다.
- Gemini 4 Carbon (
gemini-4-carbon) - Gemini 4 Argon (
gemini-4-argon) - Gemini 3.8 Flash (
gemini-3.8-flash) - Gemini 3.7 Flash (
gemini-3.7-flash) - Gemini 3.6 Flash (
gemini-3.6-flash) - Gemini 3.5 Flash-Lite (
gemini-3.5-flash-lite) - Gemini 3.5 Flash (
gemini-3.5-flash) - Gemini 3.1 Flash-Lite (
gemini-3.1-flash-lite) - Gemini 3.1 Pro (
gemini-3.1-pro-preview)
Google Cloud 계정팀을 통해 프로젝트에 허용 목록 액세스 권한이 있는 경우 다음 사이버 모델을 사용할 수도 있습니다.
- 사이버 보안을 위한 Gemini 4 Carbon(
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
시작하기 전에
결제가 사용 설정된 기존 Google Cloud 프로젝트에서 다음 기본 요건 설정 단계를 완료합니다.
-
Google 계정에 로그인합니다.
아직 계정이 없으면 새 계정을 등록하세요.
-
Google Cloud CLI를 설치합니다.
-
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
-
gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.
gcloud init Agent Platform API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기gcloud services enable aiplatform.googleapis.com
-
로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.
gcloud auth application-default login
Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.
인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.
-
Google Cloud CLI를 설치합니다.
-
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
-
gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.
gcloud init Agent Platform API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기gcloud services enable aiplatform.googleapis.com
-
로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.
gcloud auth application-default login
Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.
인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.
필요한 역할
지연된 모델 호출을 만들고, 모니터링하고, 취소하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
지연된 상호작용 만들기, 폴링, 취소, 삭제: Agent Platform 사용자(
roles/aiplatform.user) -
지연된 상호작용 모니터링(읽기 전용):
Agent Platform 뷰어(
roles/aiplatform.viewer) -
Cloud Storage에서 멀티모달 입력 파일 읽기(선택사항): 스토리지 객체 뷰어(
roles/storage.objectViewer)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
Google 생성형 AI SDK 설치
클라이언트 라이브러리를 사용하는 경우 개발 환경에 Google 생성형 AI SDK(@google/genai >= 2.32.0 또는 google-genai >= 2.34.0)를 설치하거나 업그레이드합니다.
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
지연된 모델 호출 만들기 및 관리
시작하기 전에에서 설정한 환경에서 다음 절차를 실행합니다. REST 샘플은 gcloud CLI 사용자 인증 정보로 인증하고 Google 생성형 AI SDK 샘플은 애플리케이션 기본 사용자 인증 정보(ADC)를 사용합니다. 호출에서 오류가 반환되면 문제 해결을 참조하세요.
지연된 모델 호출 만들기
service_tier="deferred", background=true, store=true를 사용하여 interactions.create를 호출하여 비동기 차례를 제출합니다. stream를 생략하거나 false로 설정합니다. 샘플을 실행하기 전에 PROJECT_ID를 Google Cloud 프로젝트 ID(예: my-agent-project)로 바꿉니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)
HTTP 메서드 및 URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
JSON 요청 본문:
{
"model": "gemini-4-argon",
"input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
"service_tier": "deferred",
"background": true,
"store": true
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
응답은 다음과 비슷한 JSON 페이로드를 반환합니다.
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
async function createDeferredInteraction(projectId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
const interaction = await ai.interactions.create({
model: "gemini-4-argon",
input:
"In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Interaction ID: ${interaction.id}`);
console.log(`Status: ${interaction.status}`);
console.log(`Service tier: ${interaction.service_tier}`);
return interaction.id ?? "";
}
await createDeferredInteraction("PROJECT_ID");
출력은 다음과 비슷합니다.
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Python
from google import genai
def create_deferred_interaction(project_id: str) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
interaction = client.interactions.create(
model="gemini-4-argon",
input=(
"In two sentences, explain how a circuit breaker differs from "
"exponential backoff in a distributed microservice architecture."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Interaction ID: {interaction.id}")
print(f"Status: {interaction.status}")
print(f"Service tier: {interaction.service_tier}")
return interaction.id or ""
create_deferred_interaction("PROJECT_ID")
출력은 다음과 비슷합니다.
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
상태 폴링 및 토큰 사용량 검색
status가 queued 또는 in_progress인 동안 백오프를 사용하여 interactions.get를 폴링합니다. 차례가 최종 상태에 도달하면 output_text 및 usage를 읽습니다.
지연 등급은 크레딧 지원 지연 시간 SLA 없이 24시간 이내에 차례의 95% 를 완료하는 것을 목표로 합니다. 다음 표에서는 Interaction 리소스의 status 값을 설명합니다.
| 상태 | 최종 | 의미 및 다음 단계 |
|---|---|---|
queued |
아니요 | 수락되었으며 용량을 기다리는 중입니다. 백오프를 사용하여 interactions.get를 폴링합니다. 아직 stream=true을(를) 요청하지 마세요. |
in_progress |
아니요 | 실행 중입니다. interactions.get를 계속 폴링하거나 stream=true를 사용하여 SSE 스트림을 연결합니다. |
requires_action |
예 | 모델에서 내보낸 function_call 단계에서 차례가 종료되었습니다. 도구를 실행한 후 previous_interaction_id로 새 대화를 만듭니다. |
requires_continuation |
예 | 부분 출력과 continuation_token로 인해 긴 디코딩 차례가 중지되었습니다. previous_interaction_id 및 continuation_token를 재개하고 input를 생략하고 max_output_tokens를 올립니다. |
completed |
예 | 차례가 끝났습니다. output_text 및 usage을(를) 읽거나 다음 차례에 id을(를) previous_interaction_id(으)로 전달합니다. |
incomplete |
예 | max_output_tokens에 도달하는 등 차례가 일찍 중지되었습니다. 부분 steps 및 usage를 검사합니다. |
failed |
예 | 차례에서 런타임 오류가 발생했거나 24시간 완료 기간을 초과했습니다. API는 expired 상태를 사용하지 않습니다. error을 검사한 후 새 요청을 제출하세요. |
cancelled |
예 | interactions.cancel 호출로 인해 완료되기 전에 차례가 중지되었습니다. |
긴 디코딩 차례가 requires_continuation로 끝나는 경우 previous_interaction_id, continuation_token, background=true, store=true, service_tier="deferred"를 사용하여 interactions.create를 호출하여 다시 시작합니다. input를 생략하고 max_output_tokens를 지금까지 생성된 토큰보다 높게 설정합니다. 각 최종 상태에 대한 청구 방식은 가격 책정 및 청구를 참고하세요.
샘플을 실행하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)INTERACTION_ID: 지연된 모델 호출을 만들 때 반환된 상호작용 ID입니다(예:v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0).
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)INTERACTION_ID: 지연된 모델 호출을 만들 때 반환된 상호작용 ID입니다(예:v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0).
HTTP 메서드 및 URL:
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
응답은 다음과 비슷한 JSON 페이로드를 반환합니다.
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "completed",
"service_tier": "deferred",
"steps": [
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
}
]
}
],
"usage": {
"total_input_tokens": 27,
"total_output_tokens": 41,
"total_tokens": 68
}
}
Node.js
import { GoogleGenAI } from "@google/genai";
const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function waitForDeferredInteraction(projectId, interactionId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
let delayMs = 5000;
let current = await ai.interactions.get(interactionId);
while (PENDING_STATES.has(current.status)) {
await sleep(delayMs);
delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
current = await ai.interactions.get(interactionId);
}
console.log(`Status: ${current.status}`);
if (current.status === "failed") {
throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
}
if (current.output_text) {
console.log(current.output_text);
}
if (current.usage) {
console.log(`Input tokens: ${current.usage.total_input_tokens}`);
console.log(`Output tokens: ${current.usage.total_output_tokens}`);
console.log(`Total tokens: ${current.usage.total_tokens}`);
}
return current.output_text ?? "";
}
await waitForDeferredInteraction(
"PROJECT_ID",
"INTERACTION_ID",
);
출력은 다음과 비슷합니다.
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
Python
import time
from google import genai
PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0
def wait_for_deferred_interaction(
project_id: str,
interaction_id: str,
) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
delay_seconds = 5.0
current = client.interactions.get(interaction_id)
while current.status in PENDING_STATES:
time.sleep(delay_seconds)
delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
current = client.interactions.get(interaction_id)
print(f"Status: {current.status}")
if current.status == "failed":
raise RuntimeError(f"Deferred turn failed: {current.error}")
if current.output_text:
print(current.output_text)
if current.usage:
print(f"Input tokens: {current.usage.total_input_tokens}")
print(f"Output tokens: {current.usage.total_output_tokens}")
print(f"Total tokens: {current.usage.total_tokens}")
return current.output_text or ""
wait_for_deferred_interaction(
"PROJECT_ID",
"INTERACTION_ID",
)
출력은 다음과 비슷합니다.
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
선택사항: 호출이 실행되는 동안 출력 스트리밍
interactions.get가 status="in_progress"를 보고한 후 stream=true를 사용하여 서버 전송 이벤트(SSE) 스트림을 연결하고 last_event_id를 사용하여 끊어진 연결을 재개할 수 있습니다.
REST
interactions.get URL에 ?stream=true을 추가합니다. 다시 연결할 때 &last_event_id=EVENT_ID도 추가하여 EVENT_ID를 마지막으로 수신된 이벤트 ID로 바꿉니다.
Node.js
await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId })를 반복하고 event.event_id를 기록하고 step.delta 이벤트에서 event.delta?.text를 읽습니다.
Python
client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id)를 반복하고 event.event_id를 기록하고 step.delta 이벤트에서 event.delta.text를 읽습니다.
SSE 스트리밍 및 재연결에 대한 자세한 내용은 Interactions API 개발자 가이드를 참고하세요.
멀티턴 지연 워크플로 연결
previous_interaction_id에서 completed 또는 requires_action 상호작용의 id를 전달하여 멀티턴 대화를 계속하거나 도구 실행 결과를 반환합니다. tools, system_instruction, generation_config와 같은 대화 범위 필드는 자동으로 전달되지 않으므로 필요한 각 대화에서 전달합니다. 연결된 대화는 암시적 컨텍스트 캐싱에 계속 사용할 수 있지만 캐시된 프리픽스는 몇 시간 동안 대기열에서 대기하는 동안 만료될 수 있습니다. 도구 결과 단계 스키마는 Interactions API 개발자 가이드를 참고하세요.
샘플을 실행하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)PREVIOUS_INTERACTION_ID: 이전completed또는requires_action차례의 ID입니다(예:v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0).
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)PREVIOUS_INTERACTION_ID: 이전 차례에서 완료되었거나 조치가 필요한 상호작용 ID입니다(예:v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0).
HTTP 메서드 및 URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
JSON 요청 본문:
{
"model": "gemini-4-argon",
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
"service_tier": "deferred",
"background": true,
"store": true
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
응답은 다음과 비슷한 JSON 페이로드를 반환합니다.
{
"id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const followUp = await ai.interactions.create({
model: "gemini-4-argon",
previous_interaction_id: "PREVIOUS_INTERACTION_ID",
input:
"Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);
출력은 다음과 비슷합니다.
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
follow_up = client.interactions.create(
model="gemini-4-argon",
previous_interaction_id="PREVIOUS_INTERACTION_ID",
input=(
"Draft a one-paragraph rollout checklist for adding a circuit "
"breaker to a payment gateway client without causing false trips."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")
출력은 다음과 비슷합니다.
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
지연된 모델 호출 취소
status가 queued 또는 in_progress인 지연된 상호작용을 중지하려면 interactions.cancel를 호출합니다. 다른 상태의 상호작용에서 interactions.cancel를 호출하면 HTTP 409("code": "aborted")가 반환됩니다. 취소가 결제에 미치는 영향에 대한 자세한 내용은 가격 책정 및 결제를 참조하세요.
샘플을 실행하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)INTERACTION_ID:queued또는in_progress상호작용의 ID입니다(예:v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ).
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID(예:my-agent-project)INTERACTION_ID: 취소할 대기 중이거나 진행 중인 상호작용의 ID입니다(예:v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ).
HTTP 메서드 및 URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
응답은 다음과 비슷한 JSON 페이로드를 반환합니다.
{
"id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
"model": "gemini-4-argon",
"status": "cancelled",
"service_tier": "deferred"
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);
출력은 다음과 같습니다.
Status: cancelled
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")
출력은 다음과 같습니다.
Status: cancelled
가격 책정, 할당량, 보안 제어
지연 등급에서 프로덕션 워크로드를 실행하기 전에 결제 규칙, 할당량, 페이로드 한도, 보안 제어를 검토하세요.
가격 책정 및 결제
지연된 모델 호출은 입력, 출력, 사고 토큰에 대한 표준 사용한 만큼만 지불 요금에 비해 50% 할인된 요금으로 청구됩니다. 결제에는 다음 규칙이 적용됩니다.
- 할인 중복 적용: 지연 할인은 계약 할인 및 암시적 컨텍스트 캐싱 토큰 할인과 중복 적용되며 캐시된 요율에 추가로 적용됩니다.
- 표준 요금으로 대체되지 않음: 지연된 요청은 표준 사용한 만큼만 지불로 전환되거나 다운그레이드되지 않으므로 할인되지 않은 주문형 요금으로 청구되지 않습니다.
- 모델 호출별 청구: 차례에서 수행하는 각 모델 호출에 대해 요금이 청구됩니다.
completed,incomplete,requires_action또는requires_continuation로 끝나는 대화는 지연 요율로 청구됩니다. - 취소된 차례:
queued상태에서 취소한 차례에는 요금이 청구되지 않습니다.in_progress상태에서 차례를 취소하면 생성 중간에 중단된 호출을 포함하여 이미 시작된 모델 호출에 요금이 청구됩니다. - 실패한 차례: 24시간 완료 기간을 초과하는 차례를 포함하여
failed로 끝나는 단일 호출 차례에는 요금이 청구되지 않습니다. 다단계 서버 측 도구 루프에서는 실패 전에 완료된 모델 호출에 요금이 청구되지만 실패한 호출에는 요금이 청구되지 않습니다. - 연결된 차례:
previous_interaction_id체인의 각 차례는 자체적으로 청구됩니다. 이후 차례를 취소하거나 이후 차례가 실패해도 이전 차례의 요금은 변경되지 않습니다.
모델별 토큰 요금은 Agent Platform 가격 책정 페이지를 참조하세요.
할당량, 페이로드 한도, 보관
지연 등급에는 자체 모델 호출 할당량이 없습니다. 지연된 호출은 Flex 사용한 만큼만 지불 할당량(flex_requests_per_minute_per_project_per_base_model, 3,000RPM)을 공유하며, 이는 interactions.create가 queued를 반환한 후 각 모델 호출에서 확인됩니다. 주요 프로젝트 할당량 및 시스템 한도는 다음과 같습니다.
- 생성 및 동시 실행 할당량: 생성 시 최대 100RPM 또는
stateful_genai_interaction_creations의 경우 무제한입니다. 할당량 등급에 따라 최대 500개의concurrent_interaction_generations - 일일 스테이트풀 처리량(고정): 프로젝트당 일일 240GiB 쓰기 및 일일 480GiB 읽기
- 페이로드 및 보관 한도:
interactions.create호출당 최대 9.75MiB의 압축되지 않은 HTTP 본문 및 7일 상태 보관 체인은 최대 100개의 고유한 Cloud Storage(gs://) URI를 지원합니다.
전체 할당량 표 및 콘솔 안내는 지연 등급 할당량 및 한도를 참조하세요.
보안 및 규정 준수 관리
지연 등급은 global 엔드포인트에서 상태를 큐에 추가하고 유지하므로 지원되는 거버넌스 제어가 규정 준수 요구사항과 일치하는지 확인합니다.
- 지원되는 제어: VPC 서비스 제어(VPC-SC, 경계 내에서 외부
mcp_server도구는 허용되지 않음), 액세스 투명성(AXT), Cloud 감사 로그, FedRAMP High - 지원되지 않는 제어: 스테이트리스(Stateless) 제로 데이터 보관(
store=false및constraints/vertexai.disableAPIStorage시행 모두"code": "invalid_request"와 함께 HTTP400반환), 고객 관리 암호화 키(CMEK), 데이터 레지던시, DoD IL5, ITAR
전체 기능 매트릭스는 생성형 AI의 보안 제어를 참조하세요.
문제 해결
다음 표에서는 지연 등급의 일반적인 오류와 해결 방법을 설명합니다.
| 오류 또는 상태 | 일반적인 원인 | 해결 방법 |
|---|---|---|
400(error.code: "invalid_request", 엔드포인트, 플래그 또는 모델) |
global 엔드포인트가 아니거나, 지원되지 않는 모델이거나, interactions.create에 잘못된 background, store 또는 stream 플래그가 있습니다. |
지원되는 모델로 locations/global을 타겟팅하고 background=true 및 store=true를 설정하고 stream=true를 생략합니다. |
400(error.code: "invalid_request", 페이로드, URI 또는 도구) |
압축되지 않은 본문이 9.75MiB를 초과하거나, 체인이 100개의 gs:// URI를 초과하거나, VPC-SC 내의 외부 mcp_server 도구입니다. |
대용량 파일을 gs:// URI로 전달하고(체인당 최대 100개) VPC-SC 내에서 외부 mcp_server 도구를 생략합니다. |
400(interactions.create에 error.code: "invalid_request", interactions.delete에 status: "FAILED_PRECONDITION") |
|
|
401(status: "UNAUTHENTICATED" 또는 error.code: "authentication") |
gcloud CLI 사용자 인증 정보(REST 샘플) 또는 ADC(Google 생성형 AI SDK 샘플)가 누락되었거나 만료되었습니다. | REST 샘플의 경우 gcloud auth login를 실행합니다. Google 생성형 AI SDK 샘플의 경우 gcloud auth application-default login를 실행합니다. 그런 다음 요청을 다시 시도합니다. |
403(status: "PERMISSION_DENIED" 또는 error.code: "permission_denied") |
|
roles/aiplatform.user을 부여합니다. Cloud Storage 입력의 경우 roles/storage.objectViewer도 부여합니다. |
404(error.code: "not_found", interactions.delete에 status: "NOT_FOUND") |
상호작용 또는 previous_interaction_id이(가) 존재하지 않거나 삭제되었습니다. global 이외의 엔드포인트에 속하거나 7일 보관 기간보다 오래되었을 수도 있습니다. |
global 엔드포인트에서 상호작용 ID를 확인합니다. 상위 차례가 만료된 경우 previous_interaction_id 없이 새 체인을 시작합니다. |
409(error.code: "aborted") |
interactions.cancel이(가) 이미 최종 상태인 상호작용을 타겟팅합니다. requires_action, requires_continuation, completed, incomplete, failed 또는 cancelled |
먼저 interactions.get에서 status를 확인하세요. queued 및 in_progress 상호작용만 취소할 수 있습니다. |
429(error.code: "too_many_requests") |
프로젝트가 상호작용 생성 속도, 동시 상호작용 생성, 일일 스테이트풀(Stateful) 처리량과 같은 프로젝트별 할당량을 초과했습니다. |
|
status="failed" |
|
|
다음 단계
비동기 및 스테이트풀(Stateful) Gemini 워크로드에 대한 관련 가이드 및 참고 문서를 살펴보세요.
- 소비 옵션에서 컴퓨팅 모델 비교
- Interactions API 개발자 가이드에서 스테이트풀(Stateful) 멀티턴 애플리케이션을 빌드합니다.
- 자율 에이전트 예약에서 ADK 에이전트 및 관리형 조사 실행을 예약합니다.
- Interactions API 참조에서 메서드 스키마를 살펴보세요.