Onboard your Agent

# Nimble Search: setup prompt

You are integrating **Nimble Search** into this project.

## When to use it
Use Search when you need current web results for a query. It returns ranked
results with titles, URLs, and descriptions. If you need a written answer with
citations rather than a result list, use a Web Search Agent. If you already know
the page you want, use Extract.

## Setup
```bash
pip install nimble_python          # Python
npm install @nimble-way/nimble-js  # TypeScript
export NIMBLE_API_KEY="your-api-key"
```

## Example (Python)
```python
import os
from nimble_python import Nimble

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

result = nimble.search(
    query="best CRM tools for startups 2026",
    max_results=5,
    search_depth="lite",   # lite | fast | deep
)

for item in result.results:
    print(item.title, item.url)
```

## Notes
- `search_depth` controls cost and latency. `lite` is the default and returns
  metadata only. `deep` returns full page extraction.
- `focus` narrows the result type, for example a shopping or news focus.
- Read `total_results`. Do not assume a fixed count.

## Language notes
- TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`.
- The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. `max_results` and `search_depth` keep their underscores.
- Go takes optional scalars through `param.NewOpt(...)` and enums as typed
  constants such as `nimble.SearchParamsSearchDepthLite`.

## Links
- Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/search
- REST: POST https://sdk.nimbleway.com/v2/search
- CLI: `nimble search --query "..." --max-results 5`

## Other Nimble products

| Product | Returns | Reach for it when |
|---------|---------|-------------------|
| **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup |
| **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract |
| **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed |
| **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content |
| **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting |
| **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request |
| **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule |

# Nimble Extract Template: setup prompt

You are integrating **Nimble Extract Template** into this project.

## When to use it
Use an Extract Template for sites that already have a maintained template, such as
Amazon product pages or Google Maps. Pass a template name and its parameters and
get structured fields back. Nimble maintains the template, so it keeps working when the site changes its markup. For an arbitrary URL with
no template, use Extract.

## Setup
```bash
pip install nimble_python          # Python
npm install @nimble-way/nimble-js  # TypeScript
export NIMBLE_API_KEY="your-api-key"
```

## Example (Python)
```python
import os
from nimble_python import Nimble

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

result = nimble.extract.templates.run(
    template="amazon_pdp",
    params={"asin": "B0DKB1GWML"},
)

print(result.data.parsing)
```

## Notes
- List what exists with `nimble.extract.templates.list()` before assuming a
  template is available.
- Each template declares its own required params. Read the template first.
- A template can be generated for a site that lacks one.

## Language notes
- TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`.
- The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`.
- `params` is a free-form object. Its keys come from the template, not the SDK,
  so they are not type-checked.

## Links
- Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/extract/template
- REST: POST https://sdk.nimbleway.com/v2/extract/templates/run
- CLI: `nimble extract:templates run --template amazon_pdp`

## Other Nimble products

| Product | Returns | Reach for it when |
|---------|---------|-------------------|
| **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup |
| **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract |
| **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed |
| **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content |
| **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting |
| **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request |
| **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule |

# Nimble Extract: setup prompt

You are integrating **Nimble Extract** into this project.

## When to use it
Use Extract when you have a specific URL and want its content. It handles
JavaScript rendering and returns whichever formats you ask for. For a popular
site with a known layout, prefer an Extract Template: it returns structured
fields without selectors.

## Setup
```bash
pip install nimble_python          # Python
npm install @nimble-way/nimble-js  # TypeScript
export NIMBLE_API_KEY="your-api-key"
```

## Example (Python)
```python
import os
from nimble_python import Nimble

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

result = nimble.extract.run(
    url="https://www.nimbleway.com",
    formats=["markdown"],   # html | markdown | parsing | screenshots
)

print(result.data.markdown)
```

## Notes
- Pass `formats=["markdown"]` for LLM input. Add `"html"` only if you need raw markup.
- Heavy pages can exceed a sync request. Use the async variant and poll the task.
- Geo-targeting, stealth mode, and browser actions are per-request options.

## Language notes
- TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`.
- The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`.
- The response nests content under `data`, so read `result.data.markdown`, not
  `result.markdown`.

## Links
- Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/extract/quickstart
- REST: POST https://sdk.nimbleway.com/v2/extract
- CLI: `nimble extract run --url "..." --format markdown`

## Other Nimble products

| Product | Returns | Reach for it when |
|---------|---------|-------------------|
| **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup |
| **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract |
| **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed |
| **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content |
| **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting |
| **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request |
| **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule |

# Nimble Map: setup prompt

You are integrating **Nimble Map** into this project.

## When to use it
Use Map to plan work before extracting. It returns the URLs on a domain by
following links and reading sitemaps, without fetching page content. Pick targets
from it, then pass those URLs to Extract. To get content from every page in one
call instead, use Crawl.

## Setup
```bash
pip install nimble_python          # Python
npm install @nimble-way/nimble-js  # TypeScript
export NIMBLE_API_KEY="your-api-key"
```

## Example (Python)
```python
import os
from nimble_python import Nimble

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

result = nimble.map(
    url="https://www.nimbleway.com",
    sitemap="include",
)

for link in result.links:
    print(link.url)
```

## Notes
- Map returns links and metadata, not page content, so it costs far less to run than Crawl.
- `sitemap="include"` merges sitemap entries with discovered links.
- Large sites return a lot of URLs. Filter before extracting.

## Language notes
- TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`.
- The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`.
- Results are under `links`, each with `url`, `title`, and `description`.

## Links
- Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/map
- REST: POST https://sdk.nimbleway.com/v2/map
- CLI: `nimble map --url "..." --sitemap include`

## Other Nimble products

| Product | Returns | Reach for it when |
|---------|---------|-------------------|
| **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup |
| **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract |
| **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed |
| **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content |
| **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting |
| **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request |
| **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule |

# Nimble Extract Jobs: setup prompt

You are integrating **Nimble Extract Jobs** into this project.

## When to use it
Use an Extract Job when the same extraction has to run repeatedly. A job binds a
template to a set of inputs, a schedule, and a destination, then delivers files
there on every run. For a one-off extraction, call Extract or an Extract Template
directly instead.

## Setup
```bash
pip install nimble_python          # Python
npm install @nimble-way/nimble-js  # TypeScript
export NIMBLE_API_KEY="your-api-key"
```

## Example (Python)
```python
import os, time
from nimble_python import Nimble

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

job = nimble.jobs.create(
    name="daily_amazon_top_skus",
    extract_template_name="amazon_pdp",
    schedule={"cron": "0 7 * * *", "enabled": True},
    inputs={"type": "inline", "data": [{"asin": "B08N5WRWNW"}]},
    destination={
        "type": "s3",
        "path": "s3://my-bucket/amazon-skus/",
        "format": "parquet",
    },
)

run = nimble.jobs.runs.create(job.id)
artifacts = nimble.jobs.runs.artifacts.list(run.id)
```

## Notes
- A job needs four things: a template, inputs, a schedule, and a destination.
- `schedule.cron` is standard cron. Set `enabled: false` to create it paused.
- Trigger a run immediately with `jobs.runs.create` rather than waiting for the cron.
- Output arrives as artifacts. List them, then request a download URL.
- Destinations include S3 and Databricks; the connection is configured separately.

## Language notes
- TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`.
- The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. One exception to watch: the artifact download helper is
  `downloadURL` in TypeScript and `download_url` in Python.
- `inputs` and `destination` are free-form objects whose shape depends on the type
  you pass, so they are not fully type-checked.

## Links
- Docs: https://docs.nimbleway.com/nimble-sdk/agentic/jobs
- REST: POST https://sdk.nimbleway.com/v2/jobs
- CLI: `nimble jobs create --name ... --extract-template-name ...`

## Other Nimble products

| Product | Returns | Reach for it when |
|---------|---------|-------------------|
| **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup |
| **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract |
| **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed |
| **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content |
| **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting |
| **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request |
| **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule |