wehub-resource-sync
841 lines
32 KiB
Plaintext
841 lines
32 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "9a863221"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# Copyright 2026 Google LLC\n",
|
|
"#\n",
|
|
"# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
|
|
"# you may not use this file except in compliance with the License.\n",
|
|
"# You may obtain a copy of the License at\n",
|
|
"#\n",
|
|
"# https://www.apache.org/licenses/LICENSE-2.0\n",
|
|
"#\n",
|
|
"# Unless required by applicable law or agreed to in writing, software\n",
|
|
"# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
|
|
"# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
|
|
"# See the License for the specific language governing permissions and\n",
|
|
"# limitations under the License."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "8afd9df7"
|
|
},
|
|
"source": [
|
|
"# Introduction to Gemini Deep Research Agent\n",
|
|
"\n",
|
|
"<table align=\"left\">\n",
|
|
" <td style=\"text-align: center\">\n",
|
|
" <a href=\"https://colab.research.google.com/github/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\">\n",
|
|
" <img width=\"32px\" src=\"https://www.gstatic.com/pantheon/images/bigquery/welcome_page/colab-logo.svg\" alt=\"Google Colaboratory logo\"><br> Open in Colab\n",
|
|
" </a>\n",
|
|
" </td>\n",
|
|
" <td style=\"text-align: center\">\n",
|
|
" <a href=\"https://console.cloud.google.com/agent-platform/colab/import/https:%2F%2Fraw.githubusercontent.com%2FGoogleCloudPlatform%2Fgenerative-ai%2Fmain%2Fgemini%2Fdeep-research%2Fintro_deep_research.ipynb\">\n",
|
|
" <img width=\"32px\" src=\"https://lh3.googleusercontent.com/JmcxdQi-qOpctIvWKgPtrzZdJJK-J3sWE1RsfjZNwshCFgE_9fULcNpuXYTilIR2hjwN\" alt=\"Google Cloud Colab Enterprise logo\"><br> Open in Colab Enterprise\n",
|
|
" </a>\n",
|
|
" </td>\n",
|
|
" <td style=\"text-align: center\">\n",
|
|
" <a href=\"https://console.cloud.google.com/agent-platform/workbench/instances?download_url=https://raw.githubusercontent.com/GoogleCloudPlatform/generative-ai/main/gemini/deep-research/intro_deep_research.ipynb\">\n",
|
|
" <img width=\"32px\" src=\"https://storage.googleapis.com/github-repo/workbench-icon.svg\" alt=\"Workbench logo\"><br> Open in Workbench\n",
|
|
" </a>\n",
|
|
" </td>\n",
|
|
" <td style=\"text-align: center\">\n",
|
|
" <a href=\"https://github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\">\n",
|
|
" <img width=\"32px\" src=\"https://raw.githubusercontent.com/primer/octicons/refs/heads/main/icons/mark-github-24.svg\" alt=\"GitHub logo\"><br> View on GitHub\n",
|
|
" </a>\n",
|
|
" </td>\n",
|
|
"</table>\n",
|
|
"\n",
|
|
"<div style=\"clear: both;\"></div>\n",
|
|
"\n",
|
|
"<p>\n",
|
|
"<b>Share to:</b>\n",
|
|
"\n",
|
|
"<a href=\"https://www.linkedin.com/sharing/share-offsite/?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\" target=\"_blank\">\n",
|
|
" <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/8/81/LinkedIn_icon.svg\" alt=\"LinkedIn logo\">\n",
|
|
"</a>\n",
|
|
"\n",
|
|
"<a href=\"https://bsky.app/intent/compose?text=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\" target=\"_blank\">\n",
|
|
" <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/7/7a/Bluesky_Logo.svg\" alt=\"Bluesky logo\">\n",
|
|
"</a>\n",
|
|
"\n",
|
|
"<a href=\"https://twitter.com/intent/tweet?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\" target=\"_blank\">\n",
|
|
" <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/5/5a/X_icon_2.svg\" alt=\"X logo\">\n",
|
|
"</a>\n",
|
|
"\n",
|
|
"<a href=\"https://reddit.com/submit?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\" target=\"_blank\">\n",
|
|
" <img width=\"20px\" src=\"https://redditinc.com/hubfs/Reddit%20Inc/Brand/Reddit_Logo.png\" alt=\"Reddit logo\">\n",
|
|
"</a>\n",
|
|
"\n",
|
|
"<a href=\"https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/deep-research/intro_deep_research.ipynb\" target=\"_blank\">\n",
|
|
" <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/5/51/Facebook_f_logo_%282019%29.svg\" alt=\"Facebook logo\">\n",
|
|
"</a>\n",
|
|
"</p>"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "be579044"
|
|
},
|
|
"source": [
|
|
"| Authors |\n",
|
|
"| --- |\n",
|
|
"| [Holt Skinner](https://github.com/holtskinner) |\n",
|
|
"| [Mohan Li](https://github.com/mohanli-ml) |"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "e1f18258"
|
|
},
|
|
"source": [
|
|
"## Overview\n",
|
|
"\n",
|
|
"The Deep Research Agent on Agent Platform autonomously plans, executes, and synthesizes multi-step research tasks. Using Gemini 3.1 Pro, it bridges the gap between public web data and private enterprise context by grounding research across three distinct, high-fidelity data streams simultaneously.\n",
|
|
"\n",
|
|
"Deep Research is an agent, not just a model. It is best suited for workloads requiring an \"analyst-in-a-box\" approach rather than low-latency chat."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "4b2ab8c2"
|
|
},
|
|
"source": [
|
|
"## Get started"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "63d2b13f"
|
|
},
|
|
"source": [
|
|
"### Install Google Gen AI SDK and other required packages\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "9c2c9364"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"%pip install -U -q \"google-genai>=2.4.0\" beautifulsoup4"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "596ef453"
|
|
},
|
|
"source": [
|
|
"### Authenticate your notebook environment\n",
|
|
"\n",
|
|
"If you are running this notebook in **Google Colab**, run the cell below to authenticate your account."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "0cbdad5c"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"import sys\n",
|
|
"\n",
|
|
"if \"google.colab\" in sys.modules:\n",
|
|
" from google.colab import auth\n",
|
|
"\n",
|
|
" auth.authenticate_user()"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "b7045971"
|
|
},
|
|
"source": [
|
|
"### Set Google Cloud project information\n",
|
|
"\n",
|
|
"To get started using Agent Platform, you must have an existing Google Cloud project and [enable the Agent Platform API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).\n",
|
|
"\n",
|
|
"Learn more about [setting up a project](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects) and a [development environment](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment)."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "a3647dd7"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"import os\n",
|
|
"\n",
|
|
"from google import genai\n",
|
|
"\n",
|
|
"# fmt: off\n",
|
|
"PROJECT_ID = \"[your-project-id]\" # @param {type: \"string\", placeholder: \"[your-project-id]\", isTemplate: true}\n",
|
|
"# fmt: on\n",
|
|
"LOCATION = \"global\" # @param [\"global\"] {allow-input: true}\n",
|
|
"\n",
|
|
"if not PROJECT_ID or PROJECT_ID == \"[your-project-id]\":\n",
|
|
" PROJECT_ID = str(os.environ.get(\"GOOGLE_CLOUD_PROJECT\"))\n",
|
|
"\n",
|
|
"client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "6dc10d67"
|
|
},
|
|
"source": [
|
|
"### Load Deep Research Agent"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "b0bae354"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"AGENT_ID = \"deep-research-preview-04-2026\""
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "51e8ff58"
|
|
},
|
|
"source": [
|
|
"### Helper methods and libraries"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "9f895bc4"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"import base64\n",
|
|
"import os\n",
|
|
"import time\n",
|
|
"from typing import Any\n",
|
|
"\n",
|
|
"from IPython.display import HTML, Image, display\n",
|
|
"from bs4 import BeautifulSoup\n",
|
|
"from google.genai.interactions import (\n",
|
|
" DocumentContent,\n",
|
|
" TextContent,\n",
|
|
" UserInputStep,\n",
|
|
")\n",
|
|
"\n",
|
|
"def contains_html(text: str) -> bool:\n",
|
|
" \"\"\"Checks if the given text contains HTML tags.\"\"\"\n",
|
|
" return bool(BeautifulSoup(text, \"html.parser\").find())\n",
|
|
"\n",
|
|
"\n",
|
|
"def contains_image(content: Any) -> bool:\n",
|
|
" \"\"\"Checks if the content is a PNG image with data.\"\"\"\n",
|
|
" mime_type = getattr(content, \"mime_type\", None)\n",
|
|
" if not mime_type and isinstance(content, dict):\n",
|
|
" mime_type = content.get(\"mime_type\")\n",
|
|
" return mime_type == \"image/png\" and (\n",
|
|
" hasattr(content, \"data\") or (isinstance(content, dict) and \"data\" in content)\n",
|
|
" )\n",
|
|
"\n",
|
|
"\n",
|
|
"def render_annotation(annotation: Any, idx: int) -> None:\n",
|
|
" \"\"\"Renders a single annotation as an HTML citation.\"\"\"\n",
|
|
" if getattr(annotation, \"type\", None) == \"url_citation\":\n",
|
|
" title = getattr(annotation, \"title\", \"Source\")\n",
|
|
" url = getattr(annotation, \"url\", \"#\")\n",
|
|
" display(HTML(f'[cite: {idx}] <a href=\"{url}\" target=\"_blank\">{title}</a>'))\n",
|
|
"\n",
|
|
"\n",
|
|
"def render_content(content: Any) -> None:\n",
|
|
" \"\"\"Unified function to render different types of content (text, image, annotations).\"\"\"\n",
|
|
" if not content:\n",
|
|
" return\n",
|
|
"\n",
|
|
" if isinstance(content, str):\n",
|
|
" display_markdown(content)\n",
|
|
" return\n",
|
|
"\n",
|
|
" # Handle text\n",
|
|
" text = getattr(content, \"text\", None)\n",
|
|
" if not text and isinstance(content, dict):\n",
|
|
" text = content.get(\"text\")\n",
|
|
" if text:\n",
|
|
" if contains_html(text):\n",
|
|
" display(HTML(text))\n",
|
|
" else:\n",
|
|
" print(text, end=\"\\n\\n\", flush=True)\n",
|
|
"\n",
|
|
" # Handle images\n",
|
|
" elif contains_image(content):\n",
|
|
" data = getattr(content, \"data\", None)\n",
|
|
" if not data and isinstance(content, dict):\n",
|
|
" data = content.get(\"data\")\n",
|
|
" if data:\n",
|
|
" display(Image(base64.b64decode(data)))\n",
|
|
"\n",
|
|
" # Handle annotations\n",
|
|
" elif annotations := getattr(content, \"annotations\", None):\n",
|
|
" if not annotations and isinstance(content, dict):\n",
|
|
" annotations = content.get(\"annotations\")\n",
|
|
" for i, ann in enumerate(annotations, 1):\n",
|
|
" render_annotation(ann, i)\n",
|
|
"\n",
|
|
" # Handle nested content\n",
|
|
" else:\n",
|
|
" sub_content = getattr(content, \"content\", None)\n",
|
|
" if not sub_content and isinstance(content, dict):\n",
|
|
" sub_content = content.get(\"content\")\n",
|
|
"\n",
|
|
" if isinstance(sub_content, list):\n",
|
|
" for item in sub_content:\n",
|
|
" render_content(item)\n",
|
|
" elif isinstance(sub_content, dict):\n",
|
|
" render_content(sub_content)\n",
|
|
" else:\n",
|
|
" # Final fallback for unexpected content objects\n",
|
|
" print(content, end=\"\\n\\n\", flush=True)\n",
|
|
"\n",
|
|
"\n",
|
|
"def poll_for_results_stream(interaction_id: str) -> None:\n",
|
|
" \"\"\"Streams results for an interaction and polls until completion.\"\"\"\n",
|
|
" print(f\"✅ Task started! Streaming results for interaction: {interaction_id}\\n\")\n",
|
|
"\n",
|
|
" final_interaction = None\n",
|
|
" try:\n",
|
|
" stream = client.interactions.get(id=interaction_id, stream=True)\n",
|
|
" for event in stream:\n",
|
|
" if interaction := getattr(event, \"interaction\", None):\n",
|
|
" final_interaction = interaction\n",
|
|
"\n",
|
|
" # Process content from delta or step\n",
|
|
" if content := getattr(event, \"delta\", getattr(event, \"step\", None)):\n",
|
|
" render_content(content)\n",
|
|
"\n",
|
|
" except Exception as e:\n",
|
|
" print(f\"An error occurred during initial streaming: {e}\")\n",
|
|
" final_interaction = client.interactions.get(id=interaction_id)\n",
|
|
"\n",
|
|
" if final_interaction is None:\n",
|
|
" final_interaction = client.interactions.get(id=interaction_id)\n",
|
|
"\n",
|
|
" # Polling loop for 'in_progress' status\n",
|
|
" while final_interaction and final_interaction.status == \"in_progress\":\n",
|
|
" print(\n",
|
|
" f\"\\nInteraction {interaction_id} still in progress. Polling again in 30 seconds...\",\n",
|
|
" end=\"\",\n",
|
|
" flush=True,\n",
|
|
" )\n",
|
|
" time.sleep(30)\n",
|
|
" final_interaction = client.interactions.get(id=interaction_id)\n",
|
|
"\n",
|
|
" # Report final status\n",
|
|
" if final_interaction and final_interaction.status == \"completed\":\n",
|
|
" print(\"\\n\\n✅ Task complete!\")\n",
|
|
" if usage := getattr(final_interaction, \"usage\", None):\n",
|
|
" print(\"\\nUsage Statistics:\")\n",
|
|
" stats = {\n",
|
|
" \"Total Tokens\": \"total_tokens\",\n",
|
|
" \"Input Tokens\": \"total_input_tokens\",\n",
|
|
" \"Output Tokens\": \"total_output_tokens\",\n",
|
|
" \"Thought Tokens\": \"total_thought_tokens\",\n",
|
|
" }\n",
|
|
" for label, attr in stats.items():\n",
|
|
" print(f\"- {label}: {getattr(usage, attr, 'N/A')}\")\n",
|
|
" elif final_interaction and final_interaction.status == \"requires_action\":\n",
|
|
" print(\"\\n\\nInteraction requires action!\")\n",
|
|
" else:\n",
|
|
" status = getattr(final_interaction, \"status\", \"unknown\")\n",
|
|
" print(f\"\\n\\nInteraction ended with status: {status}\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "6c695d9e"
|
|
},
|
|
"source": [
|
|
"## Start a Research Task with Real-time Streaming\n",
|
|
"\n",
|
|
"The following example demonstrates how to initiate a research task using the SDK.\n",
|
|
"\n",
|
|
"Note on Duration: Deep Research tasks involve iterative searching and reading. Execution is comprehensive and may take significant time (minutes) to complete.\n",
|
|
"\n",
|
|
"> **⚠️ Critical Step**: An `interaction_id` is returned immediately upon initialization. The id is required to retrieve your results if the request times out or a network interruption occurs during the long-running process.\n",
|
|
"\n",
|
|
"Configuration Requirements & Limitations:\n",
|
|
"\n",
|
|
"* You must use **background execution** (set `background=True`);\n",
|
|
"* You must use **streaming mode** (set `stream=True`);\n",
|
|
"* Only text inputs are supported;\n",
|
|
"* The agent processes single turn queries only. Stateful conversation management is not supported.\n",
|
|
"\n",
|
|
"You can steer the agent's output by providing specific formatting instructions in your prompt. This allows you to structure reports into specific sections and subsections, include data tables, or adjust tone for different audiences (e.g., \"technical,\" \"executive,\" \"casual\")."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "c8064c62"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# fmt: off\n",
|
|
"prompt = \"Describe the history of AI Agents from 2024-2026. Give a very brief overview.\" # @param {type:\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[],\n",
|
|
")\n",
|
|
"interaction_id = interaction.id\n",
|
|
"\n",
|
|
"print(f\"\\n✅ Task started! Interaction ID: {interaction_id}\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "4e302dcd"
|
|
},
|
|
"source": [
|
|
"## Reconnect to or Retrieve an Interaction Stream\n",
|
|
"\n",
|
|
"The following example demonstrates how to reconnect to an existing research session to retrieve results.\n",
|
|
"\n",
|
|
"How it works:\n",
|
|
"\n",
|
|
"1. You need to specify an `interaction_id` generated in the previous step.\n",
|
|
"2. If the research is still ongoing, you will receive real-time progress updates.\n",
|
|
"3. If the research is complete, you will receive the full history and final answer."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "793fed40"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# @markdown ### 🆔 Interaction ID to fetch:\n",
|
|
"# @markdown (Leave empty if you intend to fetch the interaction created from the previous cell.)\n",
|
|
"# fmt: off\n",
|
|
"INTERACTION_ID = \"\" # @param {type: \"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction_id = INTERACTION_ID or interaction_id\n",
|
|
"\n",
|
|
"if not interaction_id:\n",
|
|
" raise RuntimeError(\"Please specify an interaction ID\")\n",
|
|
"\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "c1yK6uyrv34O"
|
|
},
|
|
"source": [
|
|
"## Multimodal Input"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "HOYdM5pnwC2v"
|
|
},
|
|
"source": [
|
|
"### Example: PDF File from URL\n",
|
|
"\n",
|
|
"Note - You can also use a URI from a Google Cloud Storage Bucket.\n",
|
|
"\n",
|
|
"For example, try `gs://github-repo/2403_05530.pdf`"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "yfGS4sG7v3o0"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"http_url = \"https://arxiv.org/pdf/1706.03762\" # @param {\"type\":\"string\"}\n",
|
|
"# fmt: off\n",
|
|
"prompt = \"Summarize this document and describe the impact it has had on the world since it was released.\" # @param {\"type\":\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[\n",
|
|
" TextContent(type=\"text\", text=prompt),\n",
|
|
" DocumentContent(\n",
|
|
" type=\"document\", mime_type=\"application/pdf\", uri=http_url\n",
|
|
" ),\n",
|
|
" ],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "WcaVQE0KwsPY"
|
|
},
|
|
"source": [
|
|
"## Multimodal Output"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "yeow4VSVwvQe"
|
|
},
|
|
"source": [
|
|
"### Generate HTML Output"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "ePoOXy3BwxZN"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# fmt: off\n",
|
|
"prompt = \"Generate an HTML table about the Google stock price in the first week of 2026.\" # @param {\"type\":\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "qPccra-fxAJM"
|
|
},
|
|
"source": [
|
|
"### Image Generation"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "grRBzburxCQi"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"prompt = \"Show me a picture of the Eiffel Tower\" # @param {\"type\":\"string\"}\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "bf3fefea4b8a"
|
|
},
|
|
"source": [
|
|
"## Grounding Tools\n",
|
|
"\n",
|
|
"The Deep Research Agent grounds its responses simultaneously across multiple distinct streams by defining them in the `tools` array.\n",
|
|
"\n",
|
|
"By default, the agent has access to information on the public internet using the Google Search and `url_context` tools, so you don't need to specify them unless you are overriding the default list.\n",
|
|
"\n",
|
|
"Here is a breakdown of how to configure the specific tool types based on your data sources:\n",
|
|
"\n",
|
|
"| Grounding Tool | Key | Note |\n",
|
|
"| :---- | :---- | :---- |\n",
|
|
"| Google Search | `google_search` | Grounds the agent on public internet data with enterprise-level privacy filtering. |\n",
|
|
"| Enterprise Web Search | `enterprise_web_search` | Grounds the agent on public internet data from trusted sources. |\n",
|
|
"| [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) | `external_data_mcp` | Securely connects to live remote servers like S\\&P Global, Bloomberg, or Moody's instead of relying on standard web searches. Use the `id` field to specify the MCP server. |\n",
|
|
"| [Agent Search](https://docs.cloud.google.com/generative-ai-app-builder/docs) | `vertex_search` | Allows the agent to reason across massive internal corpora. You must provide the path via `datastore_id`. |\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "c5080365a8fc"
|
|
},
|
|
"source": [
|
|
"### MCP Servers\n",
|
|
"\n",
|
|
"The following example shows connecting an MCP Server without authentication."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "e521130e1699"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# fmt: off\n",
|
|
"prompt = \"Use the SearchGithub tool to search for flashattention implementation.\" # @param {type:\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"url = \"https://mcp.grep.app\"\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[\n",
|
|
" {\n",
|
|
" \"type\": \"mcp_server\",\n",
|
|
" \"name\": \"test mcp server\",\n",
|
|
" \"url\": url,\n",
|
|
" }\n",
|
|
" ],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "b9cb01b745bd"
|
|
},
|
|
"source": [
|
|
"Here is an example with authentication."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "cac2139c4653"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"prompt = \"Search for papers about flash attention.\" # @param {type:\"string\"}\n",
|
|
"# fmt: off\n",
|
|
"url = \"https://deep-research-mcps.vercel.app/paper-search-mcp\" # @param {type:\"string\"}\n",
|
|
"token = \"Bearer 01727fdfdca3040e9176ff77f3798e3606f4041c60481e3143e859734ec23b13\" #@param {type:\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[\n",
|
|
" {\n",
|
|
" \"type\": \"mcp_server\",\n",
|
|
" \"name\": \"test mcp server\",\n",
|
|
" \"url\": url,\n",
|
|
" \"headers\": {\"Authorization\": token},\n",
|
|
" }\n",
|
|
" ],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "4f7954c6b62a"
|
|
},
|
|
"source": [
|
|
"### Enterprise Web Search"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "cbc6bc07c9ad"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"prompt = \"Research the latest trends and themes in AI.\" # @param {type:\"string\"}\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[{\"type\": \"google_search\", \"search_types\": [\"enterprise_web_search\"]}],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "212cb5dc00b6"
|
|
},
|
|
"source": [
|
|
"### Agent Search\n",
|
|
"\n",
|
|
"Use the following example to connect Deep Research Agent to an [Agent Search](https://docs.cloud.google.com/generative-ai-app-builder/docs) data store.\n",
|
|
"\n",
|
|
"You will need to [create a data store](https://docs.cloud.google.com/generative-ai-app-builder/docs/create-data-store-es) and [app](https://docs.cloud.google.com/generative-ai-app-builder/docs/create-engine-es) before proceeding.\n",
|
|
"\n",
|
|
"Download the following paper and upload it to your data store to test.\n",
|
|
"\n",
|
|
"- https://dl.acm.org/doi/epdf/10.1145/2741948.2741964"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"id": "f46d064d5fa1"
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"ENGINE_ID = \"[your-app-id]\" # @param {type:\"string\"}\n",
|
|
"DATASTORE_ID = \"[your-datastore-id]\" # @param {type:\"string\"}\n",
|
|
"# fmt: off\n",
|
|
"prompt = \"Using the provided search tool, summarize what Borg is.\" # @param {type:\"string\"}\n",
|
|
"# fmt: on\n",
|
|
"\n",
|
|
"interaction = client.interactions.create(\n",
|
|
" agent=AGENT_ID,\n",
|
|
" input=[\n",
|
|
" UserInputStep(\n",
|
|
" type=\"user_input\",\n",
|
|
" content=[TextContent(type=\"text\", text=prompt)],\n",
|
|
" )\n",
|
|
" ],\n",
|
|
" background=True,\n",
|
|
" tools=[\n",
|
|
" {\n",
|
|
" \"type\": \"retrieval\",\n",
|
|
" \"retrieval_types\": [\"vertex_ai_search\"],\n",
|
|
" \"vertex_ai_search_config\": {\n",
|
|
" \"engine\": f\"projects/{PROJECT_ID}/locations/global/collections/default_collection/engines/{ENGINE_ID}\",\n",
|
|
" \"datastores\": [\n",
|
|
" f\"projects/{PROJECT_ID}/locations/global/collections/default_collection/dataStores/{DATASTORE_ID}\"\n",
|
|
" ],\n",
|
|
" },\n",
|
|
" }\n",
|
|
" ],\n",
|
|
")\n",
|
|
"\n",
|
|
"interaction_id = interaction.id\n",
|
|
"poll_for_results_stream(interaction_id=interaction_id)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {
|
|
"id": "075af4fa2493"
|
|
},
|
|
"source": [
|
|
"## Best Practices\n",
|
|
"\n",
|
|
"Giving an autonomous agent access to the web and your files introduces unique dynamics:\n",
|
|
"\n",
|
|
"* **Prompt for Unknowns:** Explicitly instruct the agent on how to handle missing data. For example, tell it to state if a figure is unavailable rather than estimating it.\n",
|
|
"* **Prompt Injection Risks:** Ensure uploaded files come from trusted sources, as malicious files could contain hidden text designed to manipulate the agent's output.\n",
|
|
"* **Data Exfiltration:** Be extremely cautious when asking the agent to summarize sensitive internal data while simultaneously giving it access to browse the public web.\n",
|
|
"* **Verify Citations:** While enterprise-grade filtering is applied, always verify the citations provided in the response to ensure web sources are reputable."
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"colab": {
|
|
"name": "intro_deep_research.ipynb",
|
|
"toc_visible": true
|
|
},
|
|
"kernelspec": {
|
|
"display_name": "Python 3",
|
|
"name": "python3"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 0
|
|
}
|