Metadata-Version: 2.5
Name: openai-agents-scavio
Version: 0.5.1
Summary: 193 Scavio real-time search, extract and website crawl tools over 31 platforms (Google, YouTube, Amazon, Walmart, eBay, Target, Zillow, Booking.com, Indeed, SEC EDGAR, G2, Meta Ad Library and more) for the OpenAI Agents SDK
Project-URL: Homepage, https://scavio.dev
Project-URL: Repository, https://github.com/scavio-ai/openai-agents-scavio
Project-URL: Documentation, https://scavio.dev/docs/openai-agents
Author-email: Scavio <support@scavio.dev>
License: MIT
Keywords: agents,openai,openai-agents,scavio,search,serp,sitemap,tavily-alternative,tools,url-extract,web-crawler,web-scraping
Requires-Python: >=3.10
Requires-Dist: openai-agents>=0.17
Requires-Dist: scavio>=0.23.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# openai-agents-scavio

[Scavio](https://scavio.dev) real-time search tools for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) — **193 tools across 31 platforms, a URL reader and website map / crawl / batch**, with one API key.

Google, YouTube, Amazon, Walmart, eBay, Target, Home Depot, Reddit, X, TikTok, TikTok Shop, Instagram, Threads, LinkedIn, Kuaishou, Zillow, Redfin, Booking.com, Airbnb, Tripadvisor, Yelp, Indeed, Glassdoor, the Apple App Store, Google Play, SEC EDGAR, Companies House, G2, Capterra, Google Ads Transparency and the Meta Ad Library — plus `scavio_extract`, which reads any URL as HTML, Markdown or plain text, and five opt-in website tools that map a site's URLs, crawl a whole site, or extract a list of pages in one job.

Nothing is held back for the MCP server any more: every live Scavio endpoint is a tool in this package.

## Install

```bash
pip install openai-agents-scavio
```

Requires `scavio>=0.23.0` — the version that made `client.extract` a callable namespace carrying `map`, `crawl` and `batch`. An older SDK cannot resolve the website tools.

## Setup

Get a Scavio API key from the [Scavio Dashboard](https://dashboard.scavio.dev) (new accounts get 50 free credits, no credit card). Set `SCAVIO_API_KEY` or pass `api_key=` to the factory.

## Usage

```python
from agents import Agent, Runner
from openai_agents_scavio import get_scavio_tools

agent = Agent(
    name="Search Assistant",
    instructions="Search the web, shopping sites, and social platforms with Scavio.",
    tools=get_scavio_tools(),  # reads SCAVIO_API_KEY
)

result = Runner.run_sync(agent, "Find the top budget laptops on Amazon")
print(result.final_output)
```

### Pick your platforms

193 tools is far more than any one agent should carry. Every platform is gated by
an `enable_*` flag, all defaulting to `True` except `enable_crawl` (opt-in,
because a crawl bills per page), so disable what you do not need:

```python
tools = get_scavio_tools(
    enable_google=True,
    enable_reddit=True,
    enable_extract=True,
    enable_amazon=False,
    enable_walmart=False,
    enable_youtube=False,
    enable_tiktok=False,
    enable_instagram=False,
    # ... and so on for the rest
)
```

Pass `all=True` to register every tool regardless of the individual flags.

| Flag | Tools | Flag | Tools |
|---|---|---|---|
| `enable_google` | 14 | `enable_airbnb` | 3 |
| `enable_amazon` | 3 | `enable_glassdoor` | 4 |
| `enable_walmart` | 7 | `enable_yelp` | 3 |
| `enable_youtube` | 15 | `enable_app_store` | 3 |
| `enable_reddit` | 12 | `enable_google_play` | 3 |
| `enable_tiktok` | 11 | `enable_sec` | 6 |
| `enable_tiktok_shop` | 8 | `enable_redfin` | 3 |
| `enable_instagram` | 12 | `enable_companies_house` | 4 |
| `enable_x` | 11 | `enable_g2` | 3 |
| `enable_linkedin` | 9 | `enable_capterra` | 3 |
| `enable_threads` | 6 | `enable_google_ads` | 3 |
| `enable_kuaishou` | 14 | `enable_meta_ads` | 3 |
| `enable_ebay` | 3 | `enable_target` | 4 |
| `enable_home_depot` | 3 | `enable_zillow` | 3 |
| `enable_booking` | 3 | `enable_tripadvisor` | 4 |
| `enable_indeed` | 4 | `enable_extract` | 1 |
| `enable_crawl` (opt-in) | 5 | | |

## Tools

Each tool is named `scavio_<platform>_<action>` (`scavio_google_search`,
`scavio_ebay_search`, `scavio_sec_filings`, `scavio_meta_ads_search`), takes flat
scalar arguments, and returns the structured Scavio JSON response. Errors come
back as `{"error": "..."}` rather than raising, so a failed call never crashes
the run.

`scavio_extract` is the exception to the naming rule: it is a core endpoint
rather than a platform, and it is the one to reach for when the agent has a URL
and needs the page behind it.

```python
tools = get_scavio_tools(enable_extract=True)  # scavio_extract(url, format=, mode=)
```

### Map, crawl and batch

When one page is not enough, `enable_crawl=True` adds five website tools:
`scavio_map_website`, `scavio_crawl_website`, `scavio_crawl_status`,
`scavio_batch_extract` and `scavio_batch_status`. Map answers in one call.
Crawl and batch start a background job, **wait up to `wait_seconds` (default
45, max 300)** for it to finish, and return the job's status with its first
page of results (10 by default) either way. A job that is still `queued` or
`running` when the wait ends keeps going: the agent reads the rest, free, with
the matching status tool and `data.id`. That keeps an agent turn bounded while
a large crawl (up to 6 hours) runs on.

```python
agent = Agent(
    name="Docs Reader",
    instructions="Map the site first, then crawl only the section you need.",
    tools=get_scavio_tools(enable_crawl=True, enable_extract=True, enable_google=False),
)
result = Runner.run_sync(agent, "Crawl hono.dev/docs (max 25 pages) and summarise the routing guide")
```

**Pricing.** Map costs 1 credit in normal mode (advanced up to 2, ultra up to
10, priced by what the call needed). Crawl and batch bill **per successful
page** at extract's price for the mode -- normal and advanced 1 credit, ultra 2
-- while failed and skipped pages are free; if your balance runs out the job
stops cleanly with `stopped_reason: "insufficient_credits"`. Reading a job is
free. Crawl and map obey the site's robots.txt; results are kept for 3 days.
Plan limits (pages per crawl / active jobs / URLs per batch): Free 10/1/10,
PAYG 100/1/50, Project 500/2/100, Bootstrap 2,000/3/500, Startup
5,000/5/1,000, Growth 10,000/10/1,000. Webhooks, idempotency keys and
cancellation are on the [REST API](https://scavio.dev/docs/extract) and the
`scavio` SDK (`client.extract.cancel_crawl(...)`), not exposed as agent tools.

### Start with the resolver on lookup-first platforms

Five platforms are keyed by an id you have to look up first. Give the agent the
resolver alongside the endpoint, or it will guess an id and get a 404:

| Platform | Resolve with | Then call |
|---|---|---|
| SEC EDGAR | `scavio_sec_lookup` (ticker → CIK) | `scavio_sec_filings`, `scavio_sec_facts`, ... |
| Tripadvisor | `scavio_tripadvisor_locations` | `scavio_tripadvisor_search`, `scavio_tripadvisor_reviews` |
| Glassdoor | `scavio_glassdoor_companies` | `scavio_glassdoor_reviews`, `scavio_glassdoor_salaries` |
| Google Ads Transparency | `scavio_google_ads_advertisers` | `scavio_google_ads_search`, `scavio_google_ads_creative` |
| Companies House | `scavio_companies_house_search` | `scavio_companies_house_officers`, ... |

## Credits

Most tools cost 1 credit per call: every Google, Amazon, Reddit, X, TikTok, TikTok
Shop, eBay, Target, Zillow, Redfin, Airbnb, Booking.com, App Store, Glassdoor, SEC
EDGAR, Companies House, Google Ads Transparency and Meta Ad Library tool, plus most
YouTube and LinkedIn ones. The exceptions:

| Tool | Credits |
|---|---|
| Home Depot, Google Play, Tripadvisor, Yelp, Indeed, Capterra (all tools) | 2 |
| `scavio_youtube_search`, `scavio_youtube_shorts` | 2 |
| `scavio_youtube_streams` | 3 |
| `scavio_youtube_transcript` | 5 |
| G2 (all tools) | 5 |
| `scavio_instagram_user_posts` | 2 |
| `scavio_instagram_post`, `scavio_instagram_comment_replies` | 8 |
| every other `scavio_instagram_*` | 10 |
| `scavio_linkedin_person_posts`, `scavio_linkedin_company_posts`, `scavio_linkedin_post_comments`, `scavio_linkedin_search_jobs` | 10 |
| `scavio_linkedin_job` | 30 |

These surfaces are **body-priced** — the cost depends on what you send, not on
which tool you call:

| Tool | Credits |
|---|---|
| `scavio_walmart_search`, `scavio_walmart_category` | 1 on `domain="com"` or `"ca"`, 2 on `"com.mx"` |
| `scavio_threads_*` | 2 addressed by `user_id`, 4 by `username` |
| `scavio_kuaishou_*` | per endpoint: 1, 2, 10, or 40 for `scavio_kuaishou_videos_batch` |
| `scavio_extract` | 1 on `mode="normal"` or `"advanced"`, 2 on `"ultra"` |
| `scavio_map_website` | 1 on `mode="normal"`; up to 2 on `"advanced"`, up to 10 on `"ultra"` |
| `scavio_crawl_website`, `scavio_batch_extract` | per successful page: 1 on `"normal"` or `"advanced"`, 2 on `"ultra"`; failed and skipped pages free |
| `scavio_crawl_status`, `scavio_batch_status` | free |

Each tool's own description states its price. See [scavio.dev/docs](https://scavio.dev/docs).

## Notes on specific platforms

- **Walmart** — `device`, `delivery_zip` and `store_id` were retired. Sending them
  is not an error: the response carries a `warnings[]` array saying they were
  ignored. `domain` was *not* retired and is the price-bearing parameter.
  `scavio_walmart_offers` returns the buy-box seller only, not the full offer
  list, and `scavio_walmart_seller_products` returns roughly the first 40
  server-rendered items with no pagination at all.
- **Amazon** — `country` (a two-letter marketplace code; the UK is `gb`, not `uk`)
  replaced `domain` in 2026-07, and `sort_by`, `pages`, `category_id`,
  `merchant_id`, `language`, `currency`, `device`, `zip_code` and
  `autoselect_variant` are gone. The marketplace ignored all of them, so they
  were removed rather than kept as silent no-ops. Rank and filter yourself.
- **Google** — v2 only. `/api/v1/google` was sunset on 2026-08-04 and returns 410,
  and the v1 vocabulary (`country_code`, `language`, `page`, `search_type`,
  `light_request`) went with it. `start` is a 0-based result offset, not a page.
- **LinkedIn** — five endpoints (person contact info, company people, company
  jobs, people search, post search) were withdrawn upstream and always return
  410. They are deliberately not tools. Use `scavio_linkedin_search_jobs` with a
  company name instead of the retired per-company job listing.
- **eBay** — `scavio_ebay_seller` is a storefront profile, not a catalogue. To page
  a seller's inventory, call `scavio_ebay_search` with `seller` set and no `query`.

## Also available via MCP

If you would rather not install anything, the same endpoints are served by the
hosted MCP server:

```python
from agents import Agent
from agents.mcp.server import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    name="scavio",
    params={"url": "https://mcp.scavio.dev/mcp", "headers": {"x-api-key": "sk_live_..."}},
)
agent = Agent(name="Search Assistant", mcp_servers=[server])
```

## Links

- Scavio: https://scavio.dev
- Docs: https://scavio.dev/docs/openai-agents
- Dashboard: https://dashboard.scavio.dev
