nimble-agents-reference

Reference for nimble agent commands. Load for Step 0 agent lookup. Contains: full agent table (50+ sites across e-commerce, food, real estate, jobs, social.

SKILL.md

GitHub

nimble agent — reference

Pre-built agents for specific sites. Always faster and more reliable than manual extraction — use them whenever a matching agent exists (see Step 0 in SKILL.md).

Table of Contents


1. List agents

Parameters:

Parameter CLI flag Type Default Description
limit --limit int — Results per page
offset --offset int — Pagination offset
search --search string — Search agents by domain, vertical, or name keyword
managed_by --managed-by string — Filter by attribution (e.g. nimble)
privacy --privacy string — Filter by privacy level

CLI:

# All agents (broad lookup)
nimble agent list --limit 100

# Targeted search by domain or vertical (preferred when domain is known)
nimble agent list --limit 100 --search "amazon"
nimble agent list --limit 100 --search "ecommerce"
nimble agent list --limit 100 --search "jobs"

Python SDK:

from nimble_python import Nimble
nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

agents = nimble.agent.list()

Response fields per agent: name, display_name, description, vertical, entity_type, domain, is_public, managed_by


2. Get agent details (schema)

Parameters:

Parameter CLI flag Type Description
template_name --template-name string Agent name (required)

CLI:

nimble agent get --template-name amazon_pdp

Python SDK:

agent = nimble.agent.get(template_name="amazon_pdp")

Response: same as list item + output_schema — JSON schema mapping field names to {type, description}.


3. Run agent (sync)

Parameters:

Parameter CLI flag Type Default Description
agent --agent string required Agent name
params --params JSON required Agent input parameters
localization --localization bool false Enable zip_code/store_id localization (agent-dependent)

CLI:

nimble agent run --agent amazon_pdp --params '{"asin": "B0CHWRXH8B"}'

Python SDK:

resp = nimble.agent.run(agent="amazon_pdp", params={"asin": "B0CHWRXH8B"})
parsing = resp.data.parsing  # dict for PDP agents, list for SERP agents

Response fields: task_id, status (success/failed), status_code, data.parsing, data.html, metadata.query_duration, metadata.agent

SERP parsing items are typed Pydantic objects — call .model_dump() before json.dumps() or ** spread. PDP parsing is a plain dict.


4. Run agent (async)

Parameters:

Parameter CLI flag Type Default Description
agent --agent string required Agent name
params --params JSON required Agent input parameters
localization --localization bool false Enable localization
callback_url --callback-url string — POST callback when task completes
storage_type --storage-type string — s3 or gs
storage_url --storage-url string — Destination: s3://bucket/prefix/
compress --storage-compress bool false Gzip the stored output
custom_name --storage-object-name string — Custom filename instead of task_id

CLI:

nimble agent run-async --agent amazon_pdp --params '{"asin": "B0CHWRXH8B"}' \
  --callback-url "https://your.server/callback"

Python SDK:

resp = await nimble.agent.run_async(agent="amazon_pdp", params={"asin": "B0CHWRXH8B"})
task_id = resp.task["id"]   # resp.task is a plain dict

Task states: pending → success or error — poll and fetch results via nimble-tasks reference.


5. Run agent (batch)

Submit up to 1,000 agent requests in a single call. Uses an inputs + shared_inputs pattern — shared config applies to all items, per-item params override.

Parameters:

Parameter CLI flag Type Default Description
inputs --input array required Array of per-item inputs (up to 1,000)
shared_inputs --shared-inputs JSON required Shared config: agent (required) + default params

Each item in inputs contains a params object with agent-specific inputs (e.g. asin, keyword). Per-item params are merged with shared_inputs.params — per-item values take priority.

CLI:

nimble agent run-batch \
  --shared-inputs 'agent: amazon_serp' \
  --input '{"params": {"keyword": "iphone 15"}}' \
  --input '{"params": {"keyword": "iphone 16"}}' \
  --input '{"params": {"keyword": "iphone 16 pro"}}'

Python SDK:

resp = nimble.agent.batch(
    inputs=[
        {"params": {"keyword": "iphone 15"}},
        {"params": {"keyword": "iphone 16"}},
        {"params": {"keyword": "iphone 16 pro"}},
    ],
    shared_inputs={"agent": "amazon_serp"},
)
batch_id = resp["batch_id"]

Node SDK:

const resp = await nimble.agent.batch({
  inputs: [
    { params: { keyword: "iphone 15" } },
    { params: { keyword: "iphone 16" } },
    { params: { keyword: "iphone 16 pro" } },
  ],
  sharedInputs: { agent: "amazon_serp" },
});
const batchId = resp.batch_id;

Response:

{
  "batch_id": "b7e1a2f3-...",
  "batch_size": 3,
  "tasks": [
    { "id": "task-001-uuid", "state": "pending", "batch_id": "b7e1a2f3-..." }
  ]
}

Polling: Use nimble batches progress --batch-id <batch_id> to check completion, then nimble batches get --batch-id <batch_id> to get all task IDs, then nimble tasks results --task-id <id> for each successful task. See nimble-tasks reference for the full polling flow.

Delivery options:

  • Polling — check status with batch/task IDs (default)
  • Webhooks — pass callback_url in shared_inputs; Nimble POSTs on completion
  • Cloud storage — set storage_type + storage_url in shared_inputs

Response shapes

Agent type data.parsing shape Notes
PDP (product/profile/detail) flat dict Access with .get("field")
SERP / list array of objects Iterate items; call .model_dump() in SDK
Google Search {"entities": {"OrganicResult": [...], ...}} Nested entities dict

Known agents — baked-in table

Note: Agent names containing date and random suffixes (e.g. indeed_search_2026_02_23_vlgtrsgu) are Nimble-managed and may be updated. Always run nimble agent list --limit 100 to confirm current names before use.

E-commerce — US

Site Agent Key param
Amazon product page amazon_pdp asin
Amazon search amazon_serp keyword
Amazon best sellers amazon_best_sellers —
Amazon category amazon_plp (see schema)
Walmart product walmart_pdp product_id
Walmart search walmart_serp keyword
Target product target_pdp tcin
Target search target_serp query
Best Buy product best_buy_pdp product_id
Home Depot product homedepot_pdp (see schema)
Home Depot search homedepot_serp (see schema)
Sam's Club product sams_club_pdp (see schema)
Sam's Club search sams_club_plp (see schema)
eBay search ebay_search_2026_02_23_pbgj8oft (see schema)
ASOS product asos_pdp (see schema)
ASOS search asos_serp (see schema)
Kroger product kroger_pdp (see schema)
Kroger search kroger_serp (see schema)
Foot Locker product footlocker_pdp (see schema)
Staples product staples_pdp (see schema)
Staples search staples_serp (see schema)
Office Depot product office_depot_pdp (see schema)
B&H search b_and_h_serp (see schema)
Slickdeals slickdeals_pdp (see schema)

Food delivery

Site Agent
DoorDash restaurant doordash_pdp
DoorDash search doordash_serp
Uber Eats restaurant uber_eats_pdp
Uber Eats search uber_eats_serp

Real estate

Site Agent Key params
Zillow listings zillow_plp zip_code, listing_type (sales/rentals/sold)
Zillow property zillow_pdp (see schema)
Rightmove search rightmove_search_2026_02_23_pxo1ccrm (see schema)

Jobs

Site Agent Key params
Indeed search indeed_search_2026_02_23_vlgtrsgu location, search_term
ZipRecruiter ziprecruiter_search_2026_02_23_8rtda7lg (see schema)

Search & maps

Site Agent Key param
Google search google_search query
Google Maps search google_maps_search query
Google Maps reviews google_maps_reviews place_id
Yelp search yelp_serp search_query, location (optional)

News & finance

Site Agent
BBC article bbc_info_2026_02_23_wexv71ke
BBC search bbc_search_2026_02_23_t0gj94t2
The Guardian search guardian_search_2026_02_23_nair7e5i
NYTimes search nytimes_search_2026_02_23_4zleml8l
Bloomberg search bloomberg_search_2026_02_23_a9u4p1tv
Yahoo Finance yahoo_finance_info_2026_02_23_fl3ij8ps
MarketWatch marketwatch_info_2026_02_23_zpwkys0h
Morningstar morningstar_search_2026_02_23_zicq0zdj
Polymarket polymarket_prediction_data_2026_02_24_9zhwkle8

Social media

Site Agent
Instagram post instagram_post
Instagram profile instagram_profile_by_account
Instagram reel instagram_reel
TikTok account tiktok_account
TikTok video tiktok_video_page
TikTok Shop product tiktok_shop_pdp
Facebook page facebook_page
Facebook profile facebook_profile_about_section
YouTube Shorts youtube_shorts
Pinterest search pinterest_search_2026_02_23_kxzd5awh
Quora topic quora_info_2026_02_23_99baxvhr

Travel & LLM platforms

Site Agent
Skyscanner flights skyscanner_flights
ChatGPT chatgpt
Gemini gemini
Grok grok
Perplexity perplexity

Agent gallery

open -a "Google Chrome" "https://online.nimbleway.com/pipeline-gallery"
open -a "Google Chrome" "https://online.nimbleway.com/pipeline-gallery/amazon_pdp/overview"

Agent memory — save new agents

After a successful run, save to learned/examples.json so Step 0 matches faster next time:

python3 -c "
import json, pathlib, datetime
p = pathlib.Path.home() / '.opencode/skills/nimble-web-expert/learned/examples.json'
data = json.loads(p.read_text()) if p.exists() else {'good': [], 'bad': [], 'agents': []}
data.setdefault('agents', [])
new_entry = {
    'agent_name': 'amazon_pdp',
    'tags': ['amazon', 'product', 'ecommerce', 'price', 'asin'],
    'params_example': {'asin': 'B0CHWRXH8B'},
    'last_used': str(datetime.date.today()),
    'notes': 'Returns price, title, rating, availability.'
}
if not any(a['agent_name'] == new_entry['agent_name'] for a in data['agents']):
    data['agents'].append(new_entry)
    p.write_text(json.dumps(data, indent=2))
    print('Saved.')
"