nimble-agents-reference

What this skill does

# 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](#1-list-agents)
- [2. Get agent details (schema)](#2-get-agent-details-schema)
- [3. Run agent (sync)](#3-run-agent-sync)
- [4. Run agent (async)](#4-run-agent-async)
- [5. Run agent (batch)](#5-run-agent-batch)
- [Response shapes](#response-shapes)
- [Known agents — baked-in table](#known-agents--baked-in-table)
- [Agent gallery](#agent-gallery)
- [Agent memory — save new agents](#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:**

```bash
# 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:**

```python
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:**

```bash
nimble agent get --template-name amazon_pdp
```

**Python SDK:**

```python
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:**

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

**Python SDK:**

```python
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:**

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

**Python SDK:**

```python
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:**

```bash
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:**

```python
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:**

```javascript
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:**

```json
{
  "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) | fl