From ccfc337c9711d36278b0d90917461aca0a23b515 Mon Sep 17 00:00:00 2001
From: Zahle Khan <zahle@thesys.dev>
Date: Fri, 14 Aug 2026 15:49:03 +0000
Subject: [PATCH] docs: document OpenUI Cloud web and image search tools

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../docs/agent/core-concepts/tools.mdx        |  2 +-
 .../docs/openui-cloud/build/search.mdx        | 66 +++++++++++++++++++
 .../docs/openui-cloud/how-it-works.mdx        |  4 ++
 docs/content/docs/openui-cloud/index.mdx      | 10 ++-
 docs/content/docs/openui-cloud/meta.json      |  1 +
 5 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 docs/content/docs/openui-cloud/build/search.mdx

diff --git a/docs/content/docs/agent/core-concepts/tools.mdx b/docs/content/docs/agent/core-concepts/tools.mdx
index 0b6bd4b8f..38d1c614d 100644
--- a/docs/content/docs/agent/core-concepts/tools.mdx
+++ b/docs/content/docs/agent/core-concepts/tools.mdx
@@ -60,7 +60,7 @@ This declaration is the same on OpenUI Cloud and self-hosted. Your code always r
 
 ## Built-in tools (OpenUI Cloud)
 
-OpenUI Cloud ships tools you enable without writing any implementation. Cloud holds the keys and runs them. For example, `image_search` lets the agent pull in relevant images.
+OpenUI Cloud ships tools you enable without writing any implementation. Cloud holds the keys and runs them: declare `{ type: "web_search" }` to give the agent current information, and `{ type: "image_search" }` to let it pull in real imagery for messages, slides, and reports. See [Web and image search](/docs/openui-cloud/build/search).
 
 ## Tools and artifacts
 
diff --git a/docs/content/docs/openui-cloud/build/search.mdx b/docs/content/docs/openui-cloud/build/search.mdx
new file mode 100644
index 000000000..2e644a7ef
--- /dev/null
+++ b/docs/content/docs/openui-cloud/build/search.mdx
@@ -0,0 +1,66 @@
+---
+title: Web and image search
+description: "Ground responses, slides, and reports in current information and real imagery with the built-in web search and image search tools."
+---
+
+OpenUI Cloud ships web search and image search as built-in tools. They are enabled by declaring them on a generation request: Cloud holds the provider keys and runs the search server-side, so there is nothing to implement and no key to manage in the application.
+
+- **Web search** gives the agent current information beyond the model's training data, so answers can cite what is true now instead of what the model remembers.
+- **Image search** returns absolute image URLs the agent can place directly into generated interfaces, slides, and reports, so visual output uses real imagery rather than placeholders.
+
+<video
+  src="/videos/agent/tool-call-web-search.mp4"
+  autoPlay
+  loop
+  muted
+  playsInline
+  className="w-full rounded-lg border"
+/>
+
+## Enable the tools
+
+Add them to the `tools` array of the Responses API call, alongside any artifact or function tools:
+
+```ts
+const stream = await client.responses.create({
+  model,
+  conversation: threadId,
+  input,
+  stream: true,
+  store: true,
+  tools: [
+    artifactTool({ artifacts: ["slides", "report"] }),
+    { type: "web_search" },
+    { type: "image_search" },
+  ],
+  instructions: generateSystemPrompt(),
+});
+```
+
+Declaring a tool makes it available, not mandatory: the model decides per turn whether a search helps. Both tools run inside Cloud, so the search result never passes through the application backend as a separate round trip, and the turn continues in the same stream.
+
+The scaffold from [Get Started](/docs/openui-cloud/get-started) already declares both tools.
+
+## In the interface
+
+A search runs as a regular tool call in the response stream. `AgentInterface` renders it as a tool-call card that shows the query while the search is in flight, then the agent continues the turn with the result folded in. See [Tools](/docs/agent/core-concepts/tools) for the tool-calling model in general.
+
+## In slides and reports
+
+Search is what makes generated artifacts specific rather than generic. Web search grounds the content, and image search supplies the absolute image URLs that image-bearing slide templates and report sections need.
+
+Steer this from the artifact instruction, which is the most reliable place to state how the agent should use search:
+
+```ts
+artifactTool({
+  artifacts: [
+    {
+      type: "slides",
+      instruction:
+        "Use web search to ground claims in current sources, and image-search-sourced absolute image URLs for visuals. Every image must depict the exact product, person, or place named beside it — never a metaphorical substitute or generic filler, and never one image reused for distinct entities.",
+    },
+  ],
+});
+```
+
+Being explicit about accuracy matters: without it, models tend to reach for loosely related stock imagery. For the templates that consume images, see [Slides](/docs/openui-cloud/build/slides) and [Reports](/docs/openui-cloud/build/reports).
diff --git a/docs/content/docs/openui-cloud/how-it-works.mdx b/docs/content/docs/openui-cloud/how-it-works.mdx
index 3da44c83f..438456c8f 100644
--- a/docs/content/docs/openui-cloud/how-it-works.mdx
+++ b/docs/content/docs/openui-cloud/how-it-works.mdx
@@ -76,6 +76,10 @@ Each response is checked against the component library it was generated for. By
 
 Slides and reports are generated through the Responses API. A request declares which artifact types are allowed, and the model produces them inside the same stream as the conversation. Slides and reports are stored and versioned automatically, and both support manual editing in their viewers. Slides can be exported to PowerPoint, and reports can be exported to PDF.
 
+## Built-in tools
+
+Web search and image search run inside Cloud. A request declares them in its `tools` array, and when the model calls one, Cloud executes it with its own provider keys and returns the result into the same stream. The application backend implements nothing and stores no search credentials. Search results also feed artifact generation, so slides and reports can be grounded in current information and real imagery. See [Web and image search](/docs/openui-cloud/build/search).
+
 ## Conversation persistence
 
 Conversations are stored server-side. Each turn's messages, actions, and outputs attach to a conversation thread, and generation calls reference the thread instead of resending its history. The application backend stores no chat history and runs no database. On load, AgentInterface reads threads and artifacts from the Persistence API.
diff --git a/docs/content/docs/openui-cloud/index.mdx b/docs/content/docs/openui-cloud/index.mdx
index 36ba04de2..5d9587616 100644
--- a/docs/content/docs/openui-cloud/index.mdx
+++ b/docs/content/docs/openui-cloud/index.mdx
@@ -23,8 +23,9 @@ It combines OpenUI's generative UI capabilities with reliable model access, auto
 3. **Generative UI for agents:** Let agents respond with rich, interactive interfaces instead of walls of text. Each response can assemble the components best suited to the task.
    - **Built-in component library:** Use a pre-tested, responsive, and accessible set of components: forms, inputs, interactive charts, accordions, tabs, and other layout components.
    - **Bring your own component library:** Generate interfaces using your own components and design system while OpenUI Cloud provides model reliability, output validation, and observability.
-4. **Slides:** Generate presentations from conversations using well-designed templates for charts, images, and structured content. Review decks in an interactive viewer, edit slides manually, and export them to PowerPoint.
-5. **Reports:** Generate long-form documents from conversations using rich components for metrics, charts, tables, images, and structured content. Review reports in a dedicated viewer and export them to PDF.
+4. **Web and image search:** Built-in search tools that Cloud runs server-side, with no keys or implementation of your own. Web search grounds responses in current information, and image search supplies real imagery for interfaces, slides, and reports. See [Web and image search](/docs/openui-cloud/build/search).
+5. **Slides:** Generate presentations from conversations using well-designed templates for charts, images, and structured content. Review decks in an interactive viewer, edit slides manually, and export them to PowerPoint.
+6. **Reports:** Generate long-form documents from conversations using rich components for metrics, charts, tables, images, and structured content. Review reports in a dedicated viewer and export them to PDF.
 
 ## OpenUI vs. OpenUI Cloud
 
@@ -35,6 +36,7 @@ It combines OpenUI's generative UI capabilities with reliable model access, auto
 | Component library | ⚠️ Basic component library | Production-ready built-in library or bring your own |
 | Model access and automatic fallbacks | Not included | Included |
 | Output validation | Not included | Included |
+| Web and image search | Not included | Built-in, run server-side |
 | Observability | Not included | Included |
 | Slides | Not included | Interactive viewer, manual editing, and PowerPoint export |
 | Reports | Not included | Dedicated viewer, manual editing, and PDF export |
@@ -87,6 +89,10 @@ OpenUI Cloud includes a pre-tested, responsive, and accessible set of components
 
 Connect your own design system and domain-specific components. Agents can use them to generate interfaces while OpenUI Cloud provides model reliability, output validation, and observability.
 
+## Web and image search
+
+Web search and image search are built into Cloud and enabled by declaring them on a request. Cloud holds the provider keys and runs the search, so responses can be grounded in current information and generated slides and reports can use real imagery instead of placeholders. See [Web and image search](/docs/openui-cloud/build/search).
+
 ## Slides
 
 Using OpenUI Cloud, agents can generate presentations from conversations with well-designed templates for titles, charts, images, comparisons, and other common slide layouts.
diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json
index 6715342fe..9a6f25883 100644
--- a/docs/content/docs/openui-cloud/meta.json
+++ b/docs/content/docs/openui-cloud/meta.json
@@ -8,6 +8,7 @@
     "models-and-byok",
     "---Features---",
     "build/chat",
+    "build/search",
     "build/slides",
     "build/reports",
     "production-readiness"