This section as Markdown: View Download

Serper Web Search Integration

Give your agent real Google search results as clean JSON — via Serper.dev — so content, research, and marketing agents can find current sources before they write.

Overview

This integration returns Google's organic results as structured JSON (title, link, snippet) through Serper.dev. The agent gets ranked Google results, then reads the most relevant pages with its web_fetch tool — no HTML scraping, no bot-blocking.

Why Serper and not Google's own API? Google's Custom Search JSON API is being retired (it shuts down on 2027-01-01) and no longer offers a whole-web mode for new engines. Serper returns the same Google results with none of the Google Cloud / cx setup, plus a generous free tier.

Skills that use this integration:

int-serper-search — Search the web via Serper's Google Search endpoint. Supports freshness (tbs) and locale (gl / hl); returns title / link / snippet for downstream web_fetch.

Agents that typically enable this integration:

Blog Content Editor — research trending models / news and find a fresh angle before drafting.
Social Manager / Newsletter Manager — source current, on-topic material.
Custom research or marketing agents that need the live public web.

Availability

Mode	Status	Notes
API Key (Serper.dev)	Available	A Serper.dev API key. Returns real Google results as JSON. Free tier: 2,500 searches; then ~$1 per 1,000.

Prerequisites

A Wiro API key — Authentication.
A deployed agent — Agent Overview.
A Serper.dev account — free, no credit card.

Setup

Step 1: Get a Serper.dev API key

Sign up at serper.dev — no credit card; new accounts get 2,500 free searches.
Open the dashboard and copy your API key from the API Key section.

No Google Cloud project, no Programmable Search Engine, and no cx — Serper handles whole-web Google search behind a single key.

Step 2: Save the credential to Wiro

curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "fields": [
      { "credentialkey": "serper", "fieldname": "apikey", "fieldvalue": "YOUR_SERPER_API_KEY" }
    ]
  }'

Or fill it in the panel: My Agents → open agent → Credentials → Serper Web Search.

Step 3: Enable the skill

Serper Web Search ships available but off. Turn int-serper-search on for the agent:

curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "skills": [ { "name": "int-serper-search", "enabled": true } ]
  }'

Or flip the toggle in the panel under Skills.

Step 4: Start the agent

curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "your-useragent-guid" }'

Credential Fields

Field	Type	Required	Description
`apikey`	string (secret)	Yes	Serper.dev API key. Encrypted at rest.

Credentials schema (as returned by `POST /UserAgent/Detail`)

"serper": {
  "_connected": true,
  "optional": true,
  "extra": true,
  "apikey": "***encrypted***"
}

optional and extra are true because Serper Web Search is an optional add-on: its credential card surfaces on the content presets even before the skill is toggled on.

Query options

The skill sends a single POST https://google.serper.dev/search with an X-API-KEY header and a JSON body. Beyond the required q, the useful fields are:

Field	Description
`q`	Query string (required).
`num`	Results to return (default 10). More than 10 counts as 2 searches on the Serper quota.
`page`	1-based page number for pagination.
`gl` / `hl`	Country bias / interface language (e.g. `gl=us`, `hl=en`).
`tbs`	Freshness filter: `qdr:d` day, `qdr:w` week, `qdr:m` month, `qdr:y` year.
`autocorrect`	`true` / `false` (default true).

Results are in .organic[] (title, link, snippet, position); a response may also carry answerBox, knowledgeGraph, peopleAlsoAsk and relatedSearches. Other endpoints on the same host/header: /news, /images, /scholar, /places, /shopping.

Quota & billing

Free tier: 2,500 searches per Serper account (no credit card).
Beyond free: about $1 per 1,000 searches, dropping toward $0.30 at scale. Credits expire 6 months after purchase.

Serper's search quota and cost are billed by Serper to the operator's own account — separate from Wiro credits. The skill's own turns are billed by Wiro on real LLM token usage like any other skill.

Troubleshooting

401 / 403: API key missing or invalid — re-copy it from the Serper dashboard.
400: Malformed JSON body or missing q.
429: Out of Serper credits or rate limited — top up credits or slow down.
Empty organic: Zero results for the query — the agent reports "no results" rather than retrying.
Agent says "not connected" with the key filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.