nimbleway/nimble-agents-reference

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
• 2. Get agent details (schema)
• 3. Run agent (sync)
• 4. Run agent (async)
• 5. Run agent (batch)
• Response shapes
• Known agents — baked-in table
• Agent gallery
• Agent memory — save new agents

---

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() / '.claude/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.')
"