> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asquareportal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web search and image research with Portal Agent

> Portal Agent can search the web, pull article summaries with citations, find images, and search YouTube — placing everything directly on your canvas.

Portal Agent includes a built-in web research capability. When you ask it to look something up, find references, or build a research board, it searches the web, fetches content from the results, and places everything on your canvas as cards — complete with source citations. You never leave the workspace to do research.

## How web search works

When you ask the agent to research a topic, it runs a web search and fetches content from the top results. For each result, it extracts the title, a summary snippet, and the source URL. The agent then places each result on the canvas as a card showing the title, snippet, source domain, and a link back to the original article.

The agent can fetch up to 10 results per search query. By default it retrieves 5.

<Steps>
  <Step title="Ask the agent to research a topic">
    Type a research request in the agent chat. You can be as specific or broad as you like — the agent will form its own search query.

    ```text theme={null}
    Research the latest developments in quantum computing and add cards for each major finding
    ```
  </Step>

  <Step title="The agent searches and fetches content">
    The agent calls `web_search` with a tailored query. You will see the tool call appear in the chat as the agent works. It fetches titles, snippets, and source URLs from multiple results simultaneously.
  </Step>

  <Step title="Results appear on the canvas as citation cards">
    Each result becomes an article card on your canvas showing the headline, a brief summary, and the source domain. Cards link back to the original URL so you can open the full article at any time.
  </Step>
</Steps>

## web\_search tool parameters

| Parameter    | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `query`      | string | Yes      | The search query to execute                      |
| `numResults` | number | No       | Number of results to fetch (default: 5, max: 10) |

## create\_article\_card tool parameters

The agent creates one card per result using `create_article_card`:

| Parameter   | Type   | Required | Description                      |
| ----------- | ------ | -------- | -------------------------------- |
| `title`     | string | Yes      | Article headline                 |
| `snippet`   | string | Yes      | Summary text                     |
| `url`       | string | Yes      | Source URL                       |
| `thumbnail` | string | No       | Optional thumbnail image URL     |
| `x`         | number | No       | Optional world-space X placement |
| `y`         | number | No       | Optional world-space Y placement |

## Image search

Portal Agent can find real images from the web and add them to your canvas. Use image search when you need visual references, moodboard assets, or design inspiration.

The `image_search` tool searches multiple sources and falls back automatically if one service is unavailable or throttled.

| Parameter    | Type   | Required | Description                                    |
| ------------ | ------ | -------- | ---------------------------------------------- |
| `query`      | string | Yes      | What to search for                             |
| `maxResults` | number | No       | Maximum images to return (default: 8, max: 12) |

<Note>
  `image_search` finds existing images on the web. To generate a new AI image, use `generate_image` instead.
</Note>

### Example image search prompts

```text theme={null}
Find 8 images of minimalist interior design for a moodboard
```

```text theme={null}
Search for inspiration images for a dark-mode mobile app UI
```

```text theme={null}
Get reference images of mid-century modern furniture
```

## YouTube search

The agent can search YouTube and add video result cards to the canvas using `youtube_search` and `create_youtube_result_card`.

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `query`      | string | Yes      | Search terms for YouTube               |
| `maxResults` | number | No       | Number of results (default: 3, max: 6) |

Video cards show the title, channel name, duration, and thumbnail — and link directly to the YouTube URL.

```text theme={null}
Find three YouTube tutorials on Figma auto-layout and add them to the canvas
```

## Research workflow example

The agent can combine web search, image search, and card creation into a single multi-step workflow from one prompt.

```text theme={null}
Research sustainable architecture and create a moodboard with key article summaries and reference images
```

The agent will:

1. Call `web_search` to find articles on sustainable architecture
2. Call `image_search` to find visual references
3. Create article cards for each result with citations
4. Place image cards alongside the article cards
5. Arrange everything into a coherent layout

```text theme={null}
Search for the top 5 AI tools released in 2025, summarize each one, and organize them into a comparison board
```

```text theme={null}
Build a competitive analysis board for project management apps — find articles, screenshots, and key data points
```

## Combining search results with applets

After running a web search, you can ask the agent to visualize the data it found as an interactive applet.

```text theme={null}
Search for the latest smartphone market share data, then build a pie chart applet with the actual numbers
```

The agent will search first, extract the data from the results, then pass it to `create_applet` to build the visualization — no manual data entry needed.

<Warning>
  Portals is currently in early access (v0.8.0-alpha). Web search and image search are subject to rate limits shared across all users. If results are slow or incomplete, the service is automatically falling back to alternative sources.
</Warning>