Nimble Agents

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:

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:

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:

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:

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:

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

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

Food delivery

Real estate

Jobs

Search & maps

News & finance

Social media

Travel & LLM platforms

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