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.mdresources/migrated/v1-skills/ai-search/SKILL.md
GitHubAI 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.mdfor 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_KEYmust 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
EventSourceor an equivalent approach to consume the data — do not use plainfetch().json(). - Markdown rendering: Model output is in Markdown format; it is recommended to use
streamdown@^1.1.6for streaming rendering. - Error handling: Always handle 429 (quota exceeded) and 402 (insufficient balance).
- Billing: This endpoint is billed per call; avoid unnecessary repeated calls.