Interactions API 개발자 가이드

Interactions API는 Gemini Enterprise Agent Platform에서 Gemini 모델 및 자율 에이전트를 사용하여 생성형 AI 애플리케이션을 빌드하기 위한 통합된 상태 저장 인터페이스를 제공합니다. Interactions API를 사용하여 멀티턴 대화를 실행하고, 실시간 응답을 스트리밍하고, 구조화된 출력을 적용하고, 함수 호출을 실행하고, 장기 실행 백그라운드 작업을 오케스트레이션합니다.

이 가이드에서는 Google 생성형 AI SDK를 설치하고, 클라이언트를 인증하고, 일반적인 상호작용 워크플로를 구현하는 방법을 보여줍니다. 상호작용 수명 주기에 관한 개념적 세부정보는 Interactions API 개요를 참고하세요.

시작하기 전에

Interactions API에 요청을 보내기 전에 Google Cloud프로젝트 및 개발 환경을 설정합니다.

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

주요 개념

다음 개념을 검토하여 Interactions API가 상태와 응답을 관리하는 방법을 알아보세요.

  • Interaction: Interactions API는 핵심 리소스인 Interaction을 중심으로 합니다. Interaction는 대화 또는 작업의 완전한 턴을 나타내며 모델 생각, 도구 호출, 최종 출력의 연대기를 추적합니다. 프롬프트-응답 상호작용과 복잡한 다단계 에이전트 워크플로를 위한 통합된 엔벨로프를 제공합니다.
  • 상태 저장 유지: 상호작용은 기본적으로 서버 측에 저장됩니다(Python의 경우 store=True, TypeScript/JavaScript의 경우 store: true). 저장된 상호작용은 7일 동안 유지되며 그 후 자동으로 삭제됩니다. store=False를 설정하면 스테이트리스 모드가 선택되어 서버 측 보관이 사용 중지되고 제로 데이터 보관 (ZDR)을 준수합니다. 스테이트리스 모드는 previous_interaction_id 체인 및 비동기 실행 (background=True)도 사용 중지합니다.
  • 응답 도우미: Google 생성형 AI SDK 버전 2.3.0 이상에서는 interaction.output_text, interaction.output_image, interaction.output_audio를 비롯한 상호작용 응답에 편의 속성을 제공합니다. interaction.steps[-1].content[0].text와 같이 단계 배열에 수동으로 색인을 생성하는 대신 interaction.output_text를 사용하여 텍스트 응답을 읽습니다.

요구사항

Interactions API와 통합하기 전에 환경과 요청이 다음 요구사항을 충족하는지 확인하세요.

  • SDK 버전 지원: 통합 Google 생성형 AI SDK (Python의 경우 >= 2.3.0, TypeScript 및 JavaScript의 경우 @google/genai >= 2.3.0)를 사용합니다.

    • 버전 2.3.0 이상은 응답 도우미 속성 및 에이전트 기능에 필요하며 버전 2.0.0은 기본 steps 스키마를 지원합니다.
    • 기존 SDK (google-cloud-aiplatform, @google-cloud/vertexai, google-generativeai)는 Interactions API를 지원하지 않습니다.

  • 지원되는 모델: 지원되는 Gemini 3 모델 이상을 사용합니다. 이전 모델 제품군은 이 API를 지원하지 않습니다. 지원되는 모델의 전체 목록은 지원되는 모델 및 최신 모델 버전으로 이전을 참고하세요.

  • 턴 범위 매개변수: tools, system_instruction, generation_config과 같은 구성 매개변수는 현재 턴에만 적용됩니다. 워크플로에 멀티턴 대화 전반에서 이러한 파라미터가 필요한 경우 후속 상호작용 턴마다 이러한 파라미터를 전달합니다.

Google 생성형 AI SDK 설치

선호하는 언어의 Google 생성형 AI SDK (>= 2.3.0)를 설치하거나 업그레이드합니다.

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

클라이언트 인증

다음 인증 방법 중 하나를 사용하여 Agent Platform의 Interactions API에 연결할 수 있습니다.

애플리케이션 기본 사용자 인증 정보 (ADC)가 있는 Google Cloud 프로젝트를 사용하여 연결

Google Cloud의 엔터프라이즈 워크로드 및 프로덕션 배포에는 이 인증 방법을 사용하는 것이 좋습니다. 애플리케이션 기본 사용자 인증 정보 (ADC)로 인증하려면 다음 속성으로 클라이언트를 초기화합니다.

  • enterprise=True
  • project= Google Cloud project ID
  • location="global"

아직 로컬 사용자 인증 정보를 구성하지 않은 경우 gcloud auth application-default login를 실행합니다.

다음 코드 샘플에서 PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

익스프레스 모드 (API 키)를 사용하여 연결

신속한 프로토타입 제작, 경량 스크립트 또는 API 키로 인증하는 환경에는 이 인증 방법을 사용하는 것이 좋습니다. 클라이언트를 초기화할 때 또는 x-goog-api-key HTTP 헤더에서 API 키를 전달합니다.

다음 코드 샘플에서 API_KEY를 API 키로 바꿉니다.

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

일반적인 상호작용 워크플로

클라이언트를 구성한 후 interactions.create 메서드를 사용하여 멀티턴 대화를 빌드하고, 출력 토큰을 실시간으로 스트리밍하고, 스키마 검증 JSON을 생성하고, 외부 함수를 호출하고, 자율 에이전트를 실행할 수 있습니다.

스테이트풀(Stateful) 멀티턴 대화 관리

모든 요청과 함께 전체 메시지 기록을 다시 전송해야 하는 상태 비저장 채팅 API와 달리 Interactions API는 기본적으로 서버에서 대화 상태를 관리합니다 (Python의 경우 store=True, TypeScript/JavaScript의 경우 store: true).

기존 대화를 계속하려면 이전 상호작용의 id을 previous_interaction_id 매개변수에 전달합니다. Agent Platform은 저장된 대화 컨텍스트를 자동으로 가져오고 새로운 턴을 추가합니다. store=False (TypeScript/JavaScript의 경우 store: false)를 설정하면 서버 측 지속성이 사용 중지되고 previous_interaction_id로 후속 턴을 연결할 수 없습니다.

Python

# Turn 1: Start a conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

// Turn 1: Start a conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

실시간으로 대답 스트리밍

대화형 애플리케이션의 인식된 지연 시간을 줄이려면 모델 응답이 생성될 때 스트리밍하면 됩니다. interactions.create를 호출할 때 stream=True (TypeScript/JavaScript에서는 stream: true)를 설정하여 서버 전송 이벤트의 반복 가능한 스트림을 수신합니다. step.delta 이벤트를 필터링하여 도착하는 대로 증분 텍스트 청크를 렌더링합니다.

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

구조화된 출력 생성

애플리케이션에 예측 가능하고 기계 가독형 형식의 대답이 필요한 경우 특정 JSON 스키마와 일치하도록 모델 출력을 제한할 수 있습니다. 타겟 스키마(예: Python의 Pydantic 모델 JSON 스키마 또는 TypeScript/JavaScript의 Type 스키마 객체)를 다형성 response_format 매개변수에 직접 전달합니다.

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

import { Type } from "@google/genai";

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

함수 호출 (도구 사용) 사용

함수 호출을 사용하면 모델이 최종 응답을 구성하기 전에 정보를 수집하기 위해 맞춤 함수 또는 외부 API의 실행을 요청할 수 있습니다. 상태 저장 상호작용 워크플로에서 함수 호출은 2턴 패턴을 따릅니다.

  1. 도구 선언 및 전달: 초기 요청의 tools 파라미터에 함수 선언을 제공합니다.
  2. 실행 및 결과 반환: function_call 단계의 응답 단계(interaction.steps)를 검사하고, 모델에서 제공한 arguments를 사용하여 로컬 함수를 실행하고, call_id 및 previous_interaction_id로 연결된 function_result 항목을 포함하는 후속 상호작용을 전송합니다.

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

에이전트 및 오래 걸리는 백그라운드 작업 실행

기반 모델 외에도 Interactions API를 사용하면 agent 매개변수를 사용하여 전문 자율 에이전트를 호출할 수 있습니다.

  • antigravity-preview-05-2026: 안전한 샌드박스 Linux 환경에서 코드 실행, 파일 관리, 웹 탐색을 지원하는 범용 관리형 에이전트입니다. 자세한 내용은 에이전트와 상호작용하기를 참고하세요.
  • deep-research-preview-04-2026: Gemini Deep Research 에이전트로, 다단계 웹 조사 작업을 계획하고 실행하며 여러 소스의 결과를 종합하여 포괄적인 보고서를 작성합니다. 자세한 내용은 Gemini Deep Research Agent 사용하기를 참고하세요.
  • 맞춤 에이전트: client.agents.create()로 구성되고 프로비저닝된 맞춤 에이전트 리소스입니다.

에이전트 워크플로는 완료하는 데 몇 분 정도 걸리는 경우가 많으므로 background=True를 설정하여 백그라운드에서 비동기식으로 실행하세요. API는 interaction.status이 completed로 전환될 때까지 client.interactions.get()를 사용하여 폴링할 수 있는 id이 포함된 Interaction 객체를 즉시 반환합니다.

이 샘플을 사용해 보기 전에 PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

업로드된 Cloud Storage 파일에 액세스

Interactions API를 사용하여 업로드된 Cloud Storage 파일에 액세스할 수 있습니다. 아래 예시를 참조하세요.

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Summarize the attached document:"},
        {
            "type": "document",
            "uri": "gs://my-secure-bucket/quarterly_report.pdf",
            "mime_type": "application/pdf"
        }
    ],
)

print(interaction.output_text)

Cloud Storage URI (예: gs://bucket-name/path/to/file)를 Interactions API에 전달하면 최종 사용자 인증 정보 (EUC)를 사용하여 요청이 평가됩니다. API는 백그라운드 프로젝트 서비스 에이전트가 아닌 인증된 호출자의 ID를 사용하여 Cloud Storage 객체를 가져옵니다.

상호작용 요청에서 Cloud Storage 파일을 전달하려면 호출 주 구성원 (사용자 계정, 서비스 계정 또는 제휴 ID)이 참조된 모든 객체에 대해 storage.objects.get 권한을 보유해야 합니다.

Cloud Storage 파일에 액세스하기 위한 IAM 역할 구성

storage.objects.get 권한이 포함된 표준 사전 정의된 역할 중 하나를 부여합니다.

  • 스토리지 객체 뷰어 (roles/storage.objectViewer): 객체에 대한 읽기 액세스 권한(권장)
  • 스토리지 객체 사용자 (roles/storage.objectUser): 객체에 대한 읽기 및 쓰기 액세스 권한입니다.

Google Cloud CLI를 사용하여 사용자 계정에 액세스 권한을 부여하려면 다음 명령어를 사용합니다.

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

특정 호출 서비스 계정에 액세스 권한을 부여하려면 다음 명령어를 사용하세요.

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID." \
    --role="roles/storage.objectViewer"

Cloud Storage 파일 액세스 문제 해결

호출 주 구성원에게 충분한 권한이 없으면 Interactions API에서 다음과 유사한 403 Forbidden 오류를 반환합니다.

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more GCS URIs.

이 문제를 해결하려면 인증된 호출자에게 버킷 또는 객체에 대한 스토리지 객체 뷰어 역할(roles/storage.objectViewer)을 부여하세요.

지정된 객체가 없거나 버킷 권한으로 인해 호출자가 객체의 존재 여부를 확인할 수 없는 경우 Interactions API는 다음과 유사한 404 Not Found 오류를 반환합니다.

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

이 문제를 해결하려면 Cloud Storage URI가 올바른지 확인하고 인증된 호출자에게 버킷에 대한 읽기 액세스 권한이 있는지 확인하세요.

고급 REST 워크플로

셸 기반 자동화, CI/CD 파이프라인 또는 Python이나 TypeScript/JavaScript 런타임이 없는 환경의 경우 curl를 사용하여 HTTP를 통해 Interactions API를 직접 호출할 수 있습니다.

REST 엔드포인트

다음 Interactions API 엔드포인트에 POST 요청을 보냅니다.

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

요청에서 다음 변수를 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: global (또는 구성에 필요한 경우 지원되는 맞춤 리전)으로 설정합니다.

환경 변수 및 인증 설정

다음 섹션에서 curl 예시를 실행하기 전에 프로젝트 ID, 타겟 모델 또는 에이전트 ID, 애플리케이션 기본 사용자 인증 정보에서 생성된 OAuth 2.0 액세스 토큰을 내보내세요.

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

동기 응답 형식

동기 POST 요청은 고유한 상호작용 id, 실행 status, 대화 steps, 토큰 usage 메타데이터가 포함된 JSON interaction 객체를 반환합니다.

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

멀티턴 스테이트풀 상호작용 계속하기

REST를 통해 저장된 대화를 계속하려면 이전 응답의 id를 JSON 요청 본문의 previous_interaction_id 필드에 전달합니다.

이 샘플을 사용해 보기 전에 PREVIOUS_INTERACTION_ID를 이전 상호작용에서 반환된 id로 바꿉니다.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

서버 전송 이벤트로 출력 스트리밍

REST를 통해 증분 업데이트를 스트리밍하려면 JSON 요청 본문에 "stream": true를 포함하세요.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

"stream": true가 설정되면 서버는 Transfer-Encoding: chunked 및 Content-Type: text/event-stream (서버 전송 이벤트)로 응답합니다. 스트림의 각 이벤트에는 event_type 및 단계 델타 콘텐츠가 포함된 JSON 페이로드가 포함된 data: 접두사가 포함됩니다. curl은 상호작용이 완료될 때까지 HTTP 연결을 자동으로 열어 두고 수신되는 청크를 실시간으로 stdout에 씁니다.

백그라운드에서 관리 에이전트 실행

REST를 통해 장기 실행 관리 에이전트 작업을 비동기적으로 시작하려면 타겟 agent를 지정하고 "background": true을 설정하고 "environment": "remote"을 구성합니다.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

다음 단계