ai-search

Integrates the AI Search API (Gemini 2.5 Flash + Google grounding) to perform web-aware intelligent search and return cited, summarized answers as a streaming SSE response. Use this skill whenever a u

SKILL.md

GitHub

AI Search

Overview

Calls the Huayan AI Search endpoint backed by the Gemini 2.5 Flash model and Google real-time search to perform web-grounded retrieval on any question and return an intelligent summary with cited sources.

  • Endpoint: POST https://app-dohnbj5by5mp-api-zYm4ze3j7XvL.gateway.appmedo.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse
  • Response mode: SSE streaming (Server-Sent Events). The first token may take up to 30 seconds; adjust timeout settings accordingly.
  • Billing: This endpoint is billed per call

Core Request Parameters

Parameter Type Required Description
contents array Yes Conversation content array; supports multi-turn dialogue
contents[].role string Yes Message role: user or model
contents[].parts array Yes Array of message parts
contents[].parts[].text string Yes Input text content

Response Structure (Each SSE Event)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "Spain won Euro 2024, defeating England 2-1 ..." }]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [],
      "groundingMetadata": {
        "searchEntryPoint": { "renderedContent": "<style>...</style>" },
        "groundingChunks": [
          { "web": { "uri": "https://...", "title": "wikipedia.org" } }
        ],
        "groundingSupports": [
          {
            "segment": { "startIndex": 526, "endIndex": 624, "text": "..." },
            "groundingChunkIndices": [0, 1, 2]
          }
        ],
        "webSearchQueries": ["Euro 2024 winner"]
      }
    }
  ]
}

Key Response Fields

Field Path Type Description
candidates[].content.parts[].text string Text fragment generated by the model (accumulated across streaming events)
candidates[].finishReason string Stop reason: STOP / MAX_TOKENS / SAFETY
candidates[].groundingMetadata.groundingChunks[].web.uri string Source citation URL (must be displayed in the UI)
candidates[].groundingMetadata.groundingChunks[].web.title string Source citation title
candidates[].groundingMetadata.webSearchQueries[] string Actual search queries executed

Important: Per API requirements, when displaying generated content you must show the source URLs obtained via Google Search on the page.


End-to-End Workflow

User enters a question
    ↓
Frontend calls Edge Function (POST JSON)
    ↓
Edge Function injects INTEGRATIONS_API_KEY
    ↓
Upstream SSE streaming response is proxied to the frontend
    ↓
Frontend parses the event stream with eventsource-parser
    ↓
Render Markdown with streamdown + display source citations

See references/ai-search-api.md for the full parameter table, generation-time code, and Edge Function code.


Generation-Time Usage (Direct Agent Call)

Use the built-in script for generation-time calls. The script reads INTEGRATIONS_API_KEY from the environment, calls the SSE endpoint, aggregates the streamed events, and prints one JSON line.

The Bash tool timeout MUST be set to 600000ms (600 seconds). (First-token latency can reach 30 seconds.)

# Single question
python3 <skill-path>/scripts/call_ai_search.py --query "Who won Euro 2024?"

# Multi-turn conversation (JSON array of role/parts items)
python3 <skill-path>/scripts/call_ai_search.py --contents '[{"role":"user","parts":[{"text":"..."}]}]'

The script prints {"status":"succeed","text":"...","sources":[{"uri":"...","title":"..."}],"webSearchQueries":[...]}. Per API terms, when displaying the generated content you must show the source URLs. On failure it prints an error to stderr and exits with a non-zero code.

See references/ai-search-api.md for the full parameter table.


Post-Generation Usage (In-App via Edge Function)

See the Post-Generation Usage section of references/ai-search-api.md.

Summary: Create an Edge Function ai-search.ts that proxies the client's contents array to the upstream SSE endpoint and forwards the streaming response back to the frontend. The frontend receives the stream using ky + eventsource-parser, renders the output with streamdown, and displays source citation links.


Notes

  • Key security: INTEGRATIONS_API_KEY must only be read server-side inside the Edge Function; never expose it to the frontend.
  • Source citations are mandatory: API terms require that when displaying generated content, you must show the source URLs obtained via Google Search (groundingChunks[].web.uri); omitting them violates the terms of use.
  • First-token latency: The first token may take up to 30 seconds; extend the frontend timeout accordingly to avoid false timeout errors.
  • Streaming required: The endpoint returns an SSE stream; you must use EventSource or an equivalent approach to consume the data — do not use plain fetch().json().
  • Markdown rendering: Model output is in Markdown format; it is recommended to use streamdown@^1.1.6 for streaming rendering.
  • Error handling: Always handle 429 (quota exceeded) and 402 (insufficient balance).
  • Billing: This endpoint is billed per call; avoid unnecessary repeated calls.