Gemini Deep Research 에이전트
Gemini Deep Research 에이전트
Gemini Deep Research 에이전트는 다단계 연구 작업을 자율적으로 계획하고, 실행하고, 종합해요. Gemini의 힘으로 복잡한 정보 지형을 탐색해 상세하고 출처가 명시된 보고서를 만들어 내요. 새 기능을 통해 에이전트와 협력적으로 계획을 세우고, MCP 서버로 외부 도구에 연결하고, 차트·그래프 같은 시각화를 포함하며, 문서를 직접 입력으로 제공할 수 있어요.
연구 작업은 반복적인 검색과 읽기를 수반하며 완료까지 몇 분이 걸릴 수 있어요. 에이전트를 비동기로 실행하고 결과를 폴링하거나 업데이트를 스트리밍하려면 백그라운드 실행(background=true 설정)을 사용해야 해요. 자세한 내용은 장기 실행 작업 처리를 참고하세요.
미리보기: Gemini Deep Research 에이전트는 현재 미리보기 상태예요. Deep Research 에이전트는 Interactions API에서만 단독으로 사용할 수 있어요. generate_content로는 접근할 수 없어요.
다음 예시는 백그라운드에서 연구 작업을 시작하고 결과를 폴링하는 방법을 보여줘요.
출처: 문서
본문
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
input="Research the history of Google TPUs.",
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.steps[-1].content[0].text)
break
elif interaction.status == "failed":
print(f"Research failed: {interaction.error}")
break
time.sleep(10)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
input: 'Research the history of Google TPUs.',
agent: 'deep-research-preview-04-2026',
background: true
});
console.log(`Research started: ${interaction.id}`);
while (true) {
const result = await client.interactions.get(interaction.id);
if (result.status === 'completed') {
console.log(result.steps.at(-1).content[0].text);
break;
} else if (result.status === 'failed') {
console.log(`Research failed: ${result.error}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 10000));
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Collections;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Research the history of Google TPUs."))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Research started: " + interaction.id().orElse(""));
while (true) {
interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
System.out.println(interaction.outputText().orElse(""));
break;
} else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {
System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));
break;
}
Thread.sleep(10000);
}
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Research the history of Google TPUs."),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
interaction := res.Interaction
if interaction.ID != nil {
fmt.Printf("Research started: %s\n", *interaction.ID)
}
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *interaction.ID,
})
if err != nil {
log.Fatal(err)
}
interaction = getRes.Interaction
if interaction.Status == interactions.InteractionStatusCompleted {
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
break
} else if interaction.Status == interactions.InteractionStatusFailed {
fmt.Printf("Research failed: %v\n", interaction.Errors)
break
}
time.Sleep(10 * time.Second)
}
}
REST
# 1. Start the research task
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the history of Google TPUs.",
"agent": "deep-research-preview-04-2026",
"background": true
}'
# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
지원 버전
Deep Research 에이전트는 두 가지 버전으로 제공돼요.
- Deep Research (
deep-research-preview-04-2026): 속도와 효율을 위해 설계됐으며, 클라이언트 UI로 스트리밍하기에 이상적이에요. - Deep Research Max (
deep-research-max-preview-04-2026): 자동 컨텍스트 수집과 종합을 위한 최대한의 포괄성.
협력적 계획(Collaborative planning)
협력적 계획은 에이전트가 작업을 시작하기 전에 연구 방향을 제어할 수 있게 해 줘요. 실행 전에 연구 계획을 검토하고 다듬을 수 있어요. 활성화하면 에이전트는 즉시 실행하는 대신 제안된 연구 계획을 반환해요. 그런 다음 멀티 턴 상호작용을 통해 계획을 검토하거나 수정하거나 승인할 수 있어요.
1단계: 계획 요청
첫 번째 상호작용에서 collaborative_planning=True를 설정하세요. 에이전트가 전체 보고서 대신 연구 계획을 반환해요.
Python
from google import genai
client = genai.Client()
# First interaction: request a research plan
plan_interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Do some research on Google TPUs.",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": True,
},
background=True,
)
# Wait for and retrieve the plan
while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const planInteraction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Do some research on Google TPUs.',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: true
},
background: true
});
let result;
while ((result = await client.interactions.get(planInteraction.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
// First interaction: request a research plan
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Do some research on Google TPUs."))
.agentConfig(
DeepResearchAgentConfig.builder()
.thinkingSummaries(ThinkingSummaries.AUTO)
.collaborativePlanning(true)
.build())
.background(true)
.build();
Interaction planInteraction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
// Wait for and retrieve the plan
Interaction result;
while (true) {
result =
client.interactions
.get(GetInteractionByIdRequest.builder().id(planInteraction.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
break;
}
Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
CollaborativePlanning: genai.Ptr(true),
})
// First interaction: request a research plan
planRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Do some research on Google TPUs."),
AgentConfig: &agentCfg,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
// Wait for and retrieve the plan
var result *interactions.Interaction
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *planRes.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
result = getRes.Interaction
if result.Status == interactions.InteractionStatusCompleted {
break
}
time.Sleep(5 * time.Second)
}
if result.OutputText != nil {
fmt.Println(*result.OutputText)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Do some research on Google TPUs.",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": true
},
"background": true
}'
2단계: 계획 다듬기(선택)
previous_interaction_id를 사용해 대화를 이어가며 계획을 반복해요. 계획 모드에 머무르려면 collaborative_planning=True를 유지하세요.
Python
# Second interaction: refine the plan
refined_plan = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": True,
},
previous_interaction_id=plan_interaction.id,
background=True,
)
while (result := client.interactions.get(id=refined_plan.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const refinedPlan = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Focus more on the differences between Google TPUs and competitor hardware, and less on the history.',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: true
},
previous_interaction_id: planInteraction.id,
background: true
});
let result;
while ((result = await client.interactions.get(refinedPlan.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
String planInteractionId = "PLAN_INTERACTION_ID";
// Second interaction: refine the plan
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(
InteractionsInput.of(
"Focus more on the differences between Google TPUs and competitor hardware, and less on the history."))
.agentConfig(
DeepResearchAgentConfig.builder()
.thinkingSummaries(ThinkingSummaries.AUTO)
.collaborativePlanning(true)
.build())
.previousInteractionId(planInteractionId)
.background(true)
.build();
Interaction refinedPlan =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Interaction result;
while (true) {
result =
client.interactions
.get(GetInteractionByIdRequest.builder().id(refinedPlan.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
break;
}
Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
planInteractionID := "PLAN_INTERACTION_ID"
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
CollaborativePlanning: genai.Ptr(true),
})
// Second interaction: refine the plan
refinedRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Focus more on the differences between Google TPUs and competitor hardware, and less on the history."),
AgentConfig: &agentCfg,
PreviousInteractionID: genai.Ptr(planInteractionID),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
var result *interactions.Interaction
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *refinedRes.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
result = getRes.Interaction
if result.Status == interactions.InteractionStatusCompleted {
break
}
time.Sleep(5 * time.Second)
}
if result.OutputText != nil {
fmt.Println(*result.OutputText)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": true
},
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"background": true
}'
3단계: 승인하고 실행
collaborative_planning=False로 설정해(또는 생략해) 계획을 승인하고 연구를 시작하세요.
Python
# Third interaction: approve the plan and kick off research
final_report = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Plan looks good!",
agent_config={
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": False,
},
previous_interaction_id=refined_plan.id,
background=True,
)
while (result := client.interactions.get(id=final_report.id)).status != "completed":
time.sleep(5)
print(result.steps[-1].content[0].text)
JavaScript
const finalReport = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Plan looks good!',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
collaborative_planning: false
},
previous_interaction_id: refinedPlan.id,
background: true
});
let result;
while ((result = await client.interactions.get(finalReport.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
String refinedPlanId = "REFINED_PLAN_ID";
// Third interaction: approve the plan and kick off research
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Plan looks good!"))
.agentConfig(
DeepResearchAgentConfig.builder()
.thinkingSummaries(ThinkingSummaries.AUTO)
.collaborativePlanning(false)
.build())
.previousInteractionId(refinedPlanId)
.background(true)
.build();
Interaction finalReport =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Interaction result;
while (true) {
result =
client.interactions
.get(GetInteractionByIdRequest.builder().id(finalReport.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
break;
}
Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
refinedPlanID := "REFINED_PLAN_ID"
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
CollaborativePlanning: genai.Ptr(false),
})
// Third interaction: approve the plan and kick off research
finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Plan looks good!"),
AgentConfig: &agentCfg,
PreviousInteractionID: genai.Ptr(refinedPlanID),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
var result *interactions.Interaction
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *finalRes.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
result = getRes.Interaction
if result.Status == interactions.InteractionStatusCompleted {
break
}
time.Sleep(5 * time.Second)
}
if result.OutputText != nil {
fmt.Println(*result.OutputText)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Plan looks good!",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"collaborative_planning": false
},
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"background": true
}'
시각화(Visualization)
visualization을 "auto"로 설정하면 에이전트는 연구 결과를 뒷받침하는 차트, 그래프, 기타 시각 요소를 생성할 수 있어요. 생성된 이미지는 응답 단계에 포함되고 image 델타로 스트리밍돼요. 최상의 결과를 얻으려면 쿼리에서 시각 자료를 명시적으로 요청하세요. 예를 들어 "시간에 따른 추세를 보여주는 차트를 포함해 줘" 또는 "시장 점유율을 비교하는 그래픽을 생성해 줘" 같은 식으로요. visualization을 "auto"로 설정하면 기능이 활성화되지만, 에이전트는 프롬프트가 요청할 때만 시각 자료를 생성해요.
Python
import base64
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Analyze global semiconductor market trends. Include graphics showing market share changes.",
agent_config={
"type": "deep-research",
"visualization": "auto",
},
background=True,
)
print(f"Research started: {interaction.id}")
while (result := client.interactions.get(id=interaction.id)).status != "completed":
time.sleep(5)
for step in result.steps:
if step.type == "model_output":
for content_item in step.content:
if content_item.type == "text":
print(content_item.text)
elif content_item.type == "image" and content_item.data:
image_bytes = base64.b64decode(content_item.data)
print(f"Received image: {len(image_bytes)} bytes")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Analyze global semiconductor market trends. Include graphics showing market share changes.',
agent_config: {
type: 'deep-research',
visualization: 'auto'
},
background: true
});
console.log(`Research started: ${interaction.id}`);
let result;
while ((result = await client.interactions.get(interaction.id)).status !== 'completed') {
await new Promise(r => setTimeout(r, 5000));
}
for (const step of result.steps) {
if (step.type === 'model_output') {
for (const contentItem of step.content) {
if (contentItem.type === 'text') {
console.log(contentItem.text);
} else if (contentItem.type === 'image' && contentItem.data) {
console.log(`[Image Output: ${contentItem.data.substring(0, 20)}...]`);
}
}
}
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.Visualization;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Base64;
import java.util.Collections;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(
InteractionsInput.of(
"Analyze global semiconductor market trends. Include graphics showing market share changes."))
.agentConfig(DeepResearchAgentConfig.builder().visualization(Visualization.AUTO).build())
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Research started: " + interaction.id().orElse(""));
Interaction result;
while (true) {
result =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
break;
}
Thread.sleep(5000);
}
for (Step step : result.steps().orElse(Collections.emptyList())) {
if (step instanceof ModelOutputStep) {
for (Content contentItem : ((ModelOutputStep) step).content().orElse(Collections.emptyList())) {
if (contentItem instanceof TextContent) {
System.out.println(((TextContent) contentItem).text().orElse(""));
} else if (contentItem instanceof ImageContent) {
ImageContent img = (ImageContent) contentItem;
if (img.data().isPresent()) {
byte[] imageBytes = Base64.getDecoder().decode(img.data().get());
System.out.println("Received image: " + imageBytes.length + " bytes");
}
}
}
}
}
Go
package main
import (
"context"
"encoding/base64"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
Visualization: interactions.VisualizationAuto.ToPointer(),
})
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Analyze global semiconductor market trends. Include graphics showing market share changes."),
AgentConfig: &agentCfg,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.ID != nil {
fmt.Printf("Research started: %s\n", *res.Interaction.ID)
}
var result *interactions.Interaction
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *res.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
result = getRes.Interaction
if result.Status == interactions.InteractionStatusCompleted {
break
}
time.Sleep(5 * time.Second)
}
for _, step := range result.Steps {
if outStep := step.ModelOutputStep; outStep != nil {
for _, contentItem := range outStep.Content {
if textContent := contentItem.TextContent; textContent != nil {
fmt.Println(textContent.GetText())
} else if imgContent := contentItem.ImageContent; imgContent != nil && imgContent.Data != nil {
imageBytes, err := base64.StdEncoding.DecodeString(*imgContent.Data)
if err == nil {
fmt.Printf("Received image: %d bytes\n", len(imageBytes))
}
}
}
}
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Analyze global semiconductor market trends. Include graphics showing market share changes.",
"agent_config": {
"type": "deep-research",
"visualization": "auto"
},
"background": true
}'
지원 도구
Deep Research는 여러 내장 및 외부 도구를 지원해요. 기본적으로(tools 매개변수를 제공하지 않을 때) 에이전트는 Google Search, URL Context, Code Execution에 접근할 수 있어요. 도구를 명시적으로 지정해 에이전트의 기능을 제한하거나 확장할 수 있어요.
| 도구 | 타입 값 | 설명 |
|---|---|---|
| Google Search | google_search |
공개 웹을 검색. 기본 활성화. |
| URL Context | url_context |
웹페이지 내용을 읽고 요약. 기본 활성화. |
| Code Execution | code_execution |
계산과 데이터 분석을 위해 코드 실행. 기본 활성화. |
| MCP Server | mcp_server |
외부 도구 접근을 위해 원격 MCP 서버에 연결. |
| File Search | file_search |
업로드한 문서 코퍼스 검색. |
Google Search
Google Search를 유일한 도구로 명시적으로 활성화하세요.
Python
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="What are the latest developments in quantum computing?",
tools=[{"type": "google_search"}],
background=True,
)
JavaScript
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'What are the latest developments in quantum computing?',
tools: [{ type: 'google_search' }],
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("What are the latest developments in quantum computing?"))
.tools(Arrays.asList(GoogleSearch.builder().build()))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("What are the latest developments in quantum computing?"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.GoogleSearch{}),
},
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "What are the latest developments in quantum computing?",
"tools": [{"type": "google_search"}],
"background": true
}'
URL Context
에이전트에게 특정 웹페이지를 읽고 요약하는 기능을 주세요.
Python
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Summarize the content of https://www.wikipedia.org/.",
tools=[{"type": "url_context"}],
background=True,
)
JavaScript
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Summarize the content of https://www.wikipedia.org/.',
tools: [{ type: 'url_context' }],
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Summarize the content of https://www.wikipedia.org/."))
.tools(Arrays.asList(URLContext.builder().build()))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Summarize the content of https://www.wikipedia.org/."),
Tools: []interactions.Tool{
interactions.NewTool(interactions.URLContext{}),
},
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Summarize the content of https://www.wikipedia.org/.",
"tools": [{"type": "url_context"}],
"background": true
}'
Code Execution
에이전트가 계산과 데이터 분석을 위해 코드를 실행하도록 허용하세요.
Python
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Calculate the 50th Fibonacci number.",
tools=[{"type": "code_execution"}],
background=True,
)
JavaScript
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Calculate the 50th Fibonacci number.',
tools: [{ type: 'code_execution' }],
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Calculate the 50th Fibonacci number."))
.tools(Arrays.asList(CodeExecution.builder().build()))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Calculate the 50th Fibonacci number."),
Tools: []interactions.Tool{
interactions.NewTool(interactions.CodeExecution{}),
},
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Calculate the 50th Fibonacci number.",
"agent": "deep-research-preview-04-2026",
"tools": [{"type": "code_execution"}],
"background": true
}'
MCP 서버
에이전트가 외부 도구와 서비스에 접근하도록 원격 MCP 서버에 연결하세요.
도구 구성에서 서버의 name과 url을 제공하세요. 인증 자격 증명을 전달하고 에이전트가 호출할 수 있는 도구를 제한할 수도 있어요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
type |
string |
Yes | "mcp_server"여야 함. |
name |
string |
No | MCP 서버의 표시 이름. |
url |
string |
No | MCP 서버 엔드포인트의 전체 URL. |
headers |
object |
No | 서버로 보내는 모든 요청에 HTTP 헤더로 전달되는 key-value 쌍(예: 인증 토큰). |
allowed_tools |
array |
No | 에이전트가 서버에서 호출할 수 있는 도구를 제한. |
기본 사용법
Python
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Check the status of my last server deployment.",
tools=[
{
"type": "mcp_server",
"name": "Deployment Tracker",
"url": "https://mcp.example.com/mcp",
"headers": {"Authorization": "Bearer my-token"},
}
],
background=True,
)
JavaScript
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Check the status of my last server deployment.',
tools: [
{
type: 'mcp_server',
name: 'Deployment Tracker',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer my-token' }
}
],
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Check the status of my last server deployment."))
.tools(
Arrays.asList(
MCPServer.builder()
.name("Deployment Tracker")
.url("https://mcp.example.com/mcp")
.headers(Collections.singletonMap("Authorization", "Bearer my-token"))
.build()))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Check the status of my last server deployment."),
Tools: []interactions.Tool{
interactions.NewTool(interactions.MCPServer{
Name: genai.Ptr("Deployment Tracker"),
URL: genai.Ptr("https://mcp.example.com/mcp"),
Headers: map[string]string{
"Authorization": "Bearer my-token",
},
}),
},
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": "Check the status of my last server deployment.",
"tools": [
{
"type": "mcp_server",
"name": "Deployment Tracker",
"url": "https://mcp.example.com/mcp",
"headers": {"Authorization": "Bearer my-token"}
}
],
"background": true
}'
File Search
File Search 도구를 사용해 에이전트에게 자신의 데이터에 대한 접근을 주세요.
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
input="Compare our 2025 fiscal year report against current public web news.",
agent="deep-research-preview-04-2026",
background=True,
tools=[
{
"type": "file_search",
"file_search_store_names": ['fileSearchStores/my-store-name']
}
]
)
JavaScript
const interaction = await client.interactions.create({
input: 'Compare our 2025 fiscal year report against current public web news.',
agent: 'deep-research-preview-04-2026',
background: true,
tools: [
{ type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] },
]
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(
InteractionsInput.of(
"Compare our 2025 fiscal year report against current public web news."))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/my-store-name"))
.build()))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Compare our 2025 fiscal year report against current public web news."),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/my-store-name"},
}),
},
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Compare our 2025 fiscal year report against current public web news.",
"agent": "deep-research-preview-04-2026",
"background": true,
"tools": [
{"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]},
]
}'
조정 가능성과 포맷팅
프롬프트에 특정 포맷팅 지시를 제공해 에이전트의 출력을 조정할 수 있어요. 이를 통해 보고서를 특정 섹션·하위 섹션으로 구조화하고, 데이터 표를 포함하거나, 다양한 청중("기술적", "임원용", "캐주얼" 등)에 맞춰 어조를 조절할 수 있어요.
입력 텍스트에서 원하는 출력 형식을 명시적으로 정의하세요.
Python
prompt = """
Research the competitive landscape of EV batteries.
Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
"""
interaction = client.interactions.create(
input=prompt,
agent="deep-research-preview-04-2026",
background=True
)
JavaScript
const prompt = `
Research the competitive landscape of EV batteries.
Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
`;
const interaction = await client.interactions.create({
input: prompt,
agent: 'deep-research-preview-04-2026',
background: true,
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
String prompt =
"Research the competitive landscape of EV batteries.\n\n"
+ "Format the output as a technical report with the following structure:\n"
+ "1. Executive Summary\n"
+ "2. Key Players (Must include a data table comparing capacity and chemistry)\n"
+ "3. Supply Chain Risks";
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of(prompt))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
prompt := "Research the competitive landscape of EV batteries.\n\n" +
"Format the output as a technical report with the following structure:\n" +
"1. Executive Summary\n" +
"2. Key Players (Must include a data table comparing capacity and chemistry)\n" +
"3. Supply Chain Risks"
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput(prompt),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the competitive landscape of EV batteries.\n\nFormat the output as a technical report with the following structure: \n1. Executive Summary\n2. Key Players (Must include a data table comparing capacity and chemistry)\n3. Supply Chain Risks",
"agent": "deep-research-preview-04-2026",
"background": true
}'
멀티모달 입력
Deep Research는 이미지와 문서(PDF)를 포함한 멀티모달 입력을 지원해요. 에이전트가 시각 콘텐츠를 분석하고, 제공된 입력으로 맥락화된 웹 기반 연구를 수행할 수 있게 해요.
Python
import time
from google import genai
client = genai.Client()
prompt = """Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground."""
interaction = client.interactions.create(
input=[
{"type": "text", "text": prompt},
{
"type": "image",
"mime_type": "image/jpeg",
"uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
}
],
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.steps[-1].content[0].text)
break
elif interaction.status == "failed":
print(f"Research failed: {interaction.error}")
break
time.sleep(10)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const prompt = `Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground.`;
const interaction = await client.interactions.create({
input: [
{ type: 'text', text: prompt },
{
type: 'image',
mime_type: "image/jpeg",
uri: 'https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg'
}
],
agent: 'deep-research-preview-04-2026',
background: true
});
console.log(`Research started: ${interaction.id}`);
while (true) {
const result = await client.interactions.get(interaction.id);
if (result.status === 'completed') {
console.log(result.steps.at(-1).content[0].text);
break;
} else if (result.status === 'failed') {
console.log(`Research failed: ${result.error}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 10000));
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Arrays;
import java.util.Collections;
Client client = new Client();
String prompt =
"Analyze the interspecies dynamics and behavioral risks present "
+ "in the provided image of the African watering hole. Specifically, investigate "
+ "the symbiotic relationship between the avian species and the pachyderms "
+ "shown, and conduct a risk assessment for the reticulated giraffes based on "
+ "their drinking posture relative to the specific predator visible in the "
+ "foreground.";
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(
InteractionsInput.ofContent(
Arrays.asList(
TextContent.builder().text(prompt).build(),
ImageContent.builder()
.mimeType(ImageContentMimeType.IMAGE_JPEG)
.uri(
"https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg")
.build())))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Research started: " + interaction.id().orElse(""));
while (true) {
interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
.interaction()
.get();
if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
System.out.println(interaction.outputText().orElse(""));
break;
} else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {
System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));
break;
}
Thread.sleep(10000);
}
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
prompt := "Analyze the interspecies dynamics and behavioral risks present " +
"in the provided image of the African watering hole. Specifically, investigate " +
"the symbiotic relationship between the avian species and the pachyderms " +
"shown, and conduct a risk assessment for the reticulated giraffes based on " +
"their drinking posture relative to the specific predator visible in the " +
"foreground."
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.TextContent{Text: prompt}),
interactions.NewContent(interactions.ImageContent{
MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
URI: genai.Ptr("https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"),
}),
}),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
interaction := res.Interaction
if interaction.ID != nil {
fmt.Printf("Research started: %s\n", *interaction.ID)
}
for {
getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *interaction.ID,
})
if err != nil {
log.Fatal(err)
}
interaction = getRes.Interaction
if interaction.Status == interactions.InteractionStatusCompleted {
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
break
} else if interaction.Status == interactions.InteractionStatusFailed {
fmt.Printf("Research failed: %v\n", interaction.Errors)
break
}
time.Sleep(10 * time.Second)
}
}
REST
# 1. Start the research task with image input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": [
{"type": "text", "text": "Analyze the interspecies dynamics and behavioral risks present in the provided image of the African watering hole. Specifically, investigate the symbiotic relationship between the avian species and the pachyderms shown, and conduct a risk assessment for the reticulated giraffes based on their drinking posture relative to the specific predator visible in the foreground."},
{"type": "image", "mime_type": "image/jpeg", "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"}
],
"agent": "deep-research-preview-04-2026",
"background": true
}'
# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
문서 이해
문서 이해를 사용하면 문서를 직접 멀티모달 입력으로 전달할 수 있어요. 에이전트는 제공된 문서를 분석하고 그 내용에 기반한 연구를 수행해요.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input=[
{"type": "text", "text": "What is this document about?"},
{
"type": "document",
"uri": "https://arxiv.org/pdf/1706.03762",
"mime_type": "application/pdf",
},
],
background=True,
)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: [
{ type: 'text', text: 'What is this document about?' },
{
type: 'document',
uri: 'https://arxiv.org/pdf/1706.03762',
mime_type: 'application/pdf'
}
],
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(
InteractionsInput.ofContent(
Arrays.asList(
TextContent.builder().text("What is this document about?").build(),
DocumentContent.builder()
.uri("https://arxiv.org/pdf/1706.03762")
.mimeType(DocumentContentMimeType.APPLICATION_PDF)
.build())))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.TextContent{Text: "What is this document about?"}),
interactions.NewContent(interactions.DocumentContent{
URI: genai.Ptr("https://arxiv.org/pdf/1706.03762"),
MimeType: interactions.DocumentContentMimeType("application/pdf").ToPointer(),
}),
}),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
# 1. Start the research task with document input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "deep-research-preview-04-2026",
"input": [
{"type": "text", "text": "What is this document about?"},
{"type": "document", "uri": "https://arxiv.org/pdf/1706.03762", "mime_type": "application/pdf"}
],
"background": true
}'
장기 실행 작업 처리
Deep Research는 계획, 검색, 읽기, 쓰기를 포함하는 다단계 프로세스예요. 이 주기는 일반적으로 동기 API 호출의 표준 타임아웃 제한을 초과해요.
에이전트는 background=True를 사용해야 해요. API는 부분적인 Interaction 객체를 즉시 반환해요. id 속성을 사용해 폴링을 위한 상호작용을 검색할 수 있어요. 상호작용 상태는 in_progress에서 completed 또는 failed로 전환돼요. 백그라운드 작업 관리에 대한 종합적인 안내는 백그라운드 실행을 참고하세요.
스트리밍
Deep Research는 사고 요약, 텍스트 출력, 생성된 이미지를 포함한 연구 진행 상황에 대한 실시간 업데이트를 받는 스트리밍을 지원해요. stream=True와 background=True를 설정해야 해요.
중간 추론 단계(사고)와 진행 업데이트를 받으려면 agent_config에서 thinking_summaries를 "auto"로 설정해 사고 요약을 활성화해야 해요. 이렇게 하지 않으면 스트림이 최종 결과만 제공할 수 있어요.
참고: 스트리밍 연결은 끊어지거나 만료될 수 있어요. Deep Research 작업은 더 오래 실행될 수 있으므로, 애플리케이션은 아래 예시처럼 상호작용 상태를 확인하고 다시 연결해야 해요.
스트림 이벤트 유형
| 이벤트 유형 | 델타 유형 | 설명 |
|---|---|---|
step.delta |
thought |
에이전트의 중간 추론 단계. |
step.delta |
text |
최종 텍스트 출력의 일부. |
step.delta |
image |
생성된 이미지(base64 인코딩). |
다음 예시는 자동 재연결로 연구 작업을 시작하고 스트림을 처리해요. interaction_id와 last_event_id를 추적해서 연결이 끊어져도(예: 600초 타임아웃 이후) 중단된 지점에서 재개할 수 있게 해요.
Python
from google import genai
client = genai.Client()
interaction_id = None
last_event_id = None
is_complete = False
def process_stream(stream):
global interaction_id, last_event_id, is_complete
for event in stream:
if event.event_type == "interaction.created":
interaction_id = event.interaction.id
if event.event_id:
last_event_id = event.event_id
if event.event_type == "step.delta":
if event.delta.type == "text":
print(event.delta.text, end="", flush=True)
elif event.delta.type == "thought":
print(f"Thought: {event.delta.text}", flush=True)
elif event.event_type in ("interaction.completed", "interaction.error"):
is_complete = True
stream = client.interactions.create(
input="Research the history of Google TPUs.",
agent="deep-research-preview-04-2026",
background=True,
stream=True,
agent_config={"type": "deep-research", "thinking_summaries": "auto"},
)
process_stream(stream)
# Reconnect if the connection drops
while not is_complete and interaction_id:
status = client.interactions.get(interaction_id)
if status.status != "in_progress":
break
stream = client.interactions.get(
id=interaction_id, stream=True, last_event_id=last_event_id,
)
process_stream(stream)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
let interactionId;
let lastEventId;
let isComplete = false;
async function processStream(stream) {
for await (const event of stream) {
if (event.type === 'interaction.created') {
interactionId = event.interaction.id;
}
if (event.event_id) lastEventId = event.event_id;
if (event.type === 'step.delta') {
if (event.delta.type === 'text') {
process.stdout.write(event.delta.text);
} else if (event.delta.type === 'thought') {
console.log(`Thought: ${event.delta.text}`);
}
} else if (['interaction.completed', 'interaction.error'].includes(event.type)) {
isComplete = true;
}
}
}
const stream = await client.interactions.create({
input: 'Research the history of Google TPUs.',
agent: 'deep-research-preview-04-2026',
background: true,
stream: true,
agent_config: { type: 'deep-research', thinking_summaries: 'auto' },
});
await processStream(stream);
// Reconnect if the connection drops
while (!isComplete && interactionId) {
const status = await client.interactions.get(interactionId);
if (status.status !== 'in_progress') break;
const resumeStream = await client.interactions.get(interactionId, {
stream: true, last_event_id: lastEventId,
});
await processStream(resumeStream);
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.ErrorEvent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionCreatedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.utils.EventStream;
class StreamProcessor {
String interactionId = null;
String lastEventId = null;
boolean isComplete = false;
void processStream(EventStream<InteractionSSEStreamEvent> stream) {
for (InteractionSSEStreamEvent streamEvent : stream) {
InteractionSSEEvent event = streamEvent.data().orElse(null);
if (event instanceof InteractionCreatedEvent) {
InteractionCreatedEvent created = (InteractionCreatedEvent) event;
interactionId = created.interaction().flatMap(i -> i.id()).orElse(null);
if (created.eventId().isPresent()) {
lastEventId = created.eventId().get();
}
} else if (event instanceof StepDelta) {
StepDelta stepDelta = (StepDelta) event;
if (stepDelta.eventId().isPresent()) {
lastEventId = stepDelta.eventId().get();
}
if (stepDelta.delta().isPresent()) {
if (stepDelta.delta().get() instanceof TextDelta) {
System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));
System.out.flush();
} else if (stepDelta.delta().get() instanceof ThoughtSummaryDelta) {
ThoughtSummaryDelta thought = (ThoughtSummaryDelta) stepDelta.delta().get();
Content content = thought.content().orElse(null);
if (content instanceof TextContent) {
System.out.println("Thought: " + ((TextContent) content).text().orElse(""));
}
}
}
} else if (event instanceof InteractionCompletedEvent || event instanceof ErrorEvent) {
isComplete = true;
}
}
}
}
Client client = new Client();
StreamProcessor processor = new StreamProcessor();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Research the history of Google TPUs."))
.background(true)
.stream(true)
.agentConfig(
DeepResearchAgentConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())
.build();
try (EventStream<InteractionSSEStreamEvent> stream =
client.interactions.create(CreateInteractionRequestBody.of(params)).events()) {
processor.processStream(stream);
}
// Reconnect if the connection drops
while (!processor.isComplete && processor.interactionId != null) {
Interaction status =
client.interactions
.get(GetInteractionByIdRequest.builder().id(processor.interactionId).build())
.interaction()
.get();
if (!InteractionStatus.IN_PROGRESS.equals(status.status().orElse(null))) {
break;
}
try (EventStream<InteractionSSEStreamEvent> stream =
client.interactions
.get(
GetInteractionByIdRequest.builder()
.id(processor.interactionId)
.stream(true)
.lastEventId(processor.lastEventId)
.build())
.events()) {
processor.processStream(stream);
}
}
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
"google.golang.org/genai/interactions/types/stream"
)
type StreamProcessor struct {
interactionID string
lastEventID *string
isComplete bool
}
func (p *StreamProcessor) processStream(s *stream.EventStream[interactions.InteractionSSEStreamEvent]) {
defer s.Close()
for s.Next() {
event := s.Value()
if created := event.GetDataInteractionCreated(); created != nil {
p.interactionID = created.Interaction.ID
if created.EventID != nil {
p.lastEventID = created.EventID
}
} else if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
if stepDelta.EventID != nil {
p.lastEventID = stepDelta.EventID
}
if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
fmt.Print(textDelta.GetText())
} else if thoughtDelta := stepDelta.GetDeltaThoughtSummary(); thoughtDelta != nil {
if textContent := thoughtDelta.GetContentText(); textContent != nil {
fmt.Printf("Thought: %s\n", textContent.GetText())
}
}
} else if event.GetDataInteractionCompleted() != nil || event.GetDataError() != nil {
p.isComplete = true
}
}
}
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
processor := &StreamProcessor{}
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
})
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Research the history of Google TPUs."),
Background: genai.Ptr(true),
Stream: genai.Ptr(true),
AgentConfig: &agentCfg,
}),
})
if err != nil {
log.Fatal(err)
}
processor.processStream(res.InteractionSSEStreamEvent)
// Reconnect if the connection drops
for !processor.isComplete && processor.interactionID != "" {
statusRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: processor.interactionID,
})
if err != nil || statusRes.Interaction.Status != interactions.InteractionStatusInProgress {
break
}
streamRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: processor.interactionID,
Stream: genai.Ptr(true),
LastEventID: processor.lastEventID,
})
if err != nil {
break
}
processor.processStream(streamRes.InteractionSSEStreamEvent)
}
}
REST
# 1. Start the stream (save the INTERACTION_ID from the interaction.start event
# and the last "event_id" you receive)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the history of Google TPUs.",
"agent": "deep-research-preview-04-2026",
"background": true,
"stream": true,
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto"
}
}'
# 2. If the connection drops, reconnect with your saved IDs
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
후속 질문과 상호작용
previous_interaction_id를 사용해 에이전트가 최종 보고서를 반환한 후에도 대화를 이어갈 수 있어요. 전체 작업을 다시 시작하지 않고도 연구의 특정 섹션에 대한 명확화, 요약, 심층 설명을 요청할 수 있어요.
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
input="Can you elaborate on the second point in the report?",
model="gemini-3.1-pro-preview",
previous_interaction_id="COMPLETED_INTERACTION_ID"
)
print(interaction.steps[-1].content[0].text)
JavaScript
const interaction = await client.interactions.create({
input: 'Can you elaborate on the second point in the report?',
model: 'gemini-3.1-pro-preview',
previous_interaction_id: 'COMPLETED_INTERACTION_ID'
});
console.log(interaction.steps.at(-1).content[0].text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model("gemini-3.1-pro-preview")
.input(InteractionsInput.of("Can you elaborate on the second point in the report?"))
.previousInteractionId("COMPLETED_INTERACTION_ID")
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.1-pro-preview"),
Input: interactions.NewInteractionsInput("Can you elaborate on the second point in the report?"),
PreviousInteractionID: genai.Ptr("COMPLETED_INTERACTION_ID"),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Can you elaborate on the second point in the report?",
"model": "gemini-3.1-pro-preview",
"previous_interaction_id": "COMPLETED_INTERACTION_ID"
}'
Gemini Deep Research 에이전트를 사용해야 하는 때
Deep Research는 모델이 아니라 에이전트예요. 저지연 채팅이 아니라 "상자 안의 분석가(analyst-in-a-box)" 접근이 필요한 워크로드에 가장 적합해요.
| 특징 | 표준 Gemini 모델 | Gemini Deep Research 에이전트 |
|---|---|---|
| 지연 시간 | 초 단위 | 분 단위(비동기/백그라운드) |
| 프로세스 | 생성 -> 출력 | 계획 -> 검색 -> 읽기 -> 반복 -> 출력 |
| 출력 | 대화형 텍스트, 코드, 짧은 요약 | 상세 보고서, 장문 분석, 비교 표 |
| 최적 대상 | 챗봇, 추출, 창의적 글쓰기 | 시장 분석, 실사, 문헌 검토, 경쟁 환경 분석 |
에이전트 구성
Deep Research는 agent_config 매개변수를 사용해 동작을 제어해요. 다음 필드가 있는 사전(dictionary)으로 전달하세요.
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
type |
string |
필수 | "deep-research"여야 함. |
thinking_summaries |
string |
"none" |
스트리밍 중 중간 추론 단계를 받으려면 "auto"로 설정. 비활성화하려면 "none"으로 설정. |
visualization |
string |
"auto" |
에이전트 생성 차트와 이미지를 활성화하려면 "auto"로 설정. 비활성화하려면 "off"로 설정. |
collaborative_planning |
boolean |
false |
연구 시작 전 다중 턴 계획 검토를 활성화하려면 true로 설정. |
Python
agent_config = {
"type": "deep-research",
"thinking_summaries": "auto",
"visualization": "auto",
"collaborative_planning": False,
}
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Research the competitive landscape of cloud GPUs.",
agent_config=agent_config,
background=True,
)
JavaScript
const interaction = await client.interactions.create({
agent: 'deep-research-preview-04-2026',
input: 'Research the competitive landscape of cloud GPUs.',
agent_config: {
type: 'deep-research',
thinking_summaries: 'auto',
visualization: 'auto',
collaborative_planning: false,
},
background: true,
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.Visualization;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
DeepResearchAgentConfig agentConfig =
DeepResearchAgentConfig.builder()
.thinkingSummaries(ThinkingSummaries.AUTO)
.visualization(Visualization.AUTO)
.collaborativePlanning(false)
.build();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent("deep-research-preview-04-2026")
.input(InteractionsInput.of("Research the competitive landscape of cloud GPUs."))
.agentConfig(agentConfig)
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
Visualization: interactions.VisualizationAuto.ToPointer(),
CollaborativePlanning: genai.Ptr(false),
})
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("deep-research-preview-04-2026"),
Input: interactions.NewInteractionsInput("Research the competitive landscape of cloud GPUs."),
AgentConfig: &agentCfg,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the competitive landscape of cloud GPUs.",
"agent": "deep-research-preview-04-2026",
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto",
"visualization": "auto",
"collaborative_planning": false
},
"background": true
}'
사용 가능 여부와 가격
Gemini Deep Research 에이전트는 Google AI Studio와 Gemini API의 Interactions API에서 접근할 수 있어요.
가격은 기본 Gemini 모델과 에이전트가 활용하는 특정 도구를 기반으로 한 종량제 모델을 따릅니다. 요청이 하나의 출력으로 이어지는 표준 채팅 요청과 달리, Deep Research 작업은 에이전트 워크플로예요. 단일 요청이 계획, 검색, 읽기, 추론의 자율적 루프를 촉발해요.
예상 비용
비용은 필요한 연구의 깊이에 따라 달라져요. 에이전트가 프롬프트에 답하는 데 필요한 읽기·검색 양을 자율적으로 결정해요.
- Deep Research (
deep-research-preview-04-2026): 중간 수준의 분석이 필요한 일반적인 쿼리의 경우, 에이전트는 약 80개의 검색 쿼리, 약 25만 개의 입력 토큰(약 50-70% 캐시됨), 약 6만 개의 출력 토큰을 사용할 수 있어요.- 예상 총액: 작업당 약 $1.00 – $3.00
- Deep Research Max (
deep-research-max-preview-04-2026): 심층 경쟁 환경 분석이나 광범위한 실사의 경우, 에이전트는 최대 약 160개의 검색 쿼리, 약 90만 개의 입력 토큰(약 50-70% 캐시됨), 약 8만 개의 출력 토큰을 사용할 수 있어요.- 예상 총액: 작업당 약 $3.00 – $7.00
참고: 이 수치는 미리보기 요율을 기준으로 한 추정치이며 변경될 수 있어요.
안전 고려 사항
에이전트에게 웹과 개인 파일에 대한 접근을 주는 것은 안전 위험에 대한 신중한 고려가 필요해요.
- 파일을 사용한 프롬프트 인젝션: 에이전트는 제공된 파일의 내용을 읽어요. 업로드된 문서(PDF, 텍스트 파일)가 신뢰할 수 있는 출처에서 온 것인지 확인하세요. 악성 파일은 에이전트의 출력을 조작하도록 설계된 은닉 텍스트를 포함할 수 있어요.
- 웹 콘텐츠 위험: 에이전트는 공개 웹을 검색해요. 견고한 안전 필터를 구현하지만, 에이전트가 악성 웹페이지를 만나 처리할 위험이 있어요. 출처를 검증하려면 응답에 제공된
citations을 검토하는 것이 좋아요. - 유출(Exfiltration): 에이전트가 웹을 탐색하도록 허용하면서 민감한 내부 데이터를 요약하도록 요청할 때는 주의하세요.
모범 사례
- 알 수 없는 것에 대한 프롬프트: 누락된 데이터를 처리하는 방법을 에이전트에 지시하세요. 예를 들어 프롬프트에 *"2025년 특정 수치를 사용할 수 없으면, 추정 대신 예측치이거나 사용할 수 없다고 명시해 줘"*라고 추가하세요.
- 맥락 제공: 입력 프롬프트에 배경 정보나 제약 조건을 직접 제공해 에이전트의 연구를 그라운딩하세요.
- 협력적 계획 사용: 복잡한 쿼리의 경우 협력적 계획을 활성화해 실행 전에 연구 계획을 검토하고 다듬으세요.
- 멀티모달 입력: Deep Research 에이전트는 멀티모달 입력을 지원해요. 비용이 증가하고 컨텍스트 창 넘침 위험이 있으므로 신중하게 사용하세요.
제한 사항
- 사용자 정의 도구: 현재 사용자 정의 Function Calling 도구를 제공할 수 없지만, Deep Research 에이전트와 함께 원격 MCP(Model Context Protocol) 서버를 사용할 수 있어요.
- 구조화된 출력: Deep Research 에이전트는 현재 구조화된 출력을 지원하지 않아요.
- 최대 연구 시간: Deep Research 에이전트의 최대 연구 시간은 60분이에요. 대부분의 작업은 20분 이내에 완료돼야 해요.
- 저장 요구 사항:
background=True를 사용한 에이전트 실행에는store=True가 필요해요. - Google 검색: Google Search는 기본적으로 활성화되며, 그라운딩된 결과에는 특정 제한이 적용돼요.
다음 단계
- Interactions API에 대해 자세히 알아보세요.
- File Search 도구를 사용해 자신의 데이터를 활용하는 방법을 알아보세요.
더 알아보기 (Learn more)
Gemini Deep Research 에이전트는 계획-검색-읽기-반복-출력의 자율적 워크플로로 상세하고 인용된 연구 보고서를 만들어요. background=True로 비동기 실행하고, 협력적 계획·시각화·MCP 서버 연결·멀티모달 입력을 활용할 수 있어요. 상호작용 기반 워크플로에 대한 안내는 Interactions API와 File Search 문서를 이어서 살펴보세요.