> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# For Coding Agents

> A self-contained reference for Claude Code, Cursor, Codex and other coding agents building on Web Search Agents

This page compresses the Web Search Agent guides into one reference a coding agent can hold in context. Fetch it as markdown at `https://docs.nimbleway.com/nimble-sdk/web-search-agents/for-coding-agents.md`, or paste the setup prompt below into your coding agent.

## Setup prompt

```text theme={"system"}
You are integrating Nimble Web Search Agents (POST https://sdk.nimbleway.com/v2/agents/runs,
Bearer auth with NIMBLE_API_KEY). Read https://docs.nimbleway.com/nimble-sdk/web-search-agents/for-coding-agents.md
first and follow its rules.

Before writing code, classify the task:
- one closed fact → use Nimble Search with include_answer, not an agent
- a known URL → use Nimble Extract or an Extract Template, not an agent
- rows that need more columns → agent, use_case=enrichment, effort=high
- a list of entities matching criteria → agent, use_case=dataset_building, effort=high
- an open question needing a sourced brief → agent, use_case=research, effort=medium (high if a schema is attached)

Create one agent by agent_name and reuse it. Put the playbook in skill, 3 to 6 checkable
requirements in goals, and only this run's question in input. Known rows go in input_data,
never in the prompt. Use a flat output_schema with 5 to 8 described fields, nullable for
anything uncertain, enums for judgments, no format/pattern/$ref, and no confidence fields.
Poll GET /v2/agents/{agent_id}/runs/{run_id} while is_active, then GET .../result.
Treat completed as "finished", not "correct": compare rows returned to rows asked, check fill,
and dedupe on your own key. Batch enrichment at about 5 rows for 6 researched fields (hard cap 20 rows, 200 cells).
```

## Endpoints

| Call | Method and path | Notes |
| - | - | - |
| Create or reuse an agent and run it | `POST /v2/agents/runs` | `agent_name` makes the agent stable across calls. `use_case`, `skill`, `goals` apply on the call that creates it |
| Run an existing agent | `POST /v2/agents/{agent_id}/runs` | `input`, optional `input_data`, `output_schema`, `sources`, `effort`, `previous_interaction_id` |
| Poll | `GET /v2/agents/{agent_id}/runs/{run_id}` | Loop while `is_active` is true. `409` on `/result` while active |
| Result | `GET /v2/agents/{agent_id}/runs/{run_id}/result` | `output.content` (text or JSON) and `output.trust` |
| Stream | `GET /v2/agents/{agent_id}/runs/{run_id}/events` | SSE; create the run with `enable_events: true` |
| Create, get, update, list agents | `POST/GET/PATCH /v2/agents` | Update is JSON Patch |

SDKs: `nimble_python` (`nimble.agents.run`, `nimble.agents.runs.get`, `nimble.agents.runs.result`), `@nimble-way/nimble-js`, `github.com/Nimbleway/nimble-go`, CLI `nimble agents run` / `nimble agents:runs get|result`. Method names are camelCase in TypeScript; body fields stay snake\_case.

## Rules

**Route first.** Search for one fact. Extract or a template for a known URL. Agent for discovery, multi-source synthesis, or filling columns.

**Use case is fixed at creation.** `research`, `enrichment`, `dataset_building`. A later run with a different value returns `422`. `dataset_building` requires effort `high` or above.

**Effort.** Research free text: `medium`. Research with schema, enrichment, dataset building: `high`. `x-high` for hard enrichment fields (one row per run) or an exhaustive single-site catalog. Never `low` for anything needing citations. `max` is not available.

**Instructions.** `skill` = objective, approach, steps, absence and disambiguation rules. `goals` = 3 to 6 checkable requirements. `input` = this run's entity and question, short. Name the entity with two keys (name plus domain). State a row cap, a stop rule ("do not stop before N unless the criteria are exhausted") and an absence rule ("null, never inferred"). Name channels to search. Avoid "all" and "every" on the open web.

**Schema.** Array root for dataset building and for enrichment with a list in `input_data` (a list of rows requires a table-shaped schema; the API returns `422` otherwise). Object root for research and single-record enrichment. 5 to 8 fields, every one with a description stating format, unit and null rule. `["string","null"]` for uncertain fields, `required` on identity fields only. Enums for classification with a `cannot_verify` value. Numbers as numbers. A `source_url` field when downstream needs evidence. No `format`, `pattern`, `min*`, `max*`, `$ref`, root `anyOf`. Depth ≤5, ≤100 properties. No `confidence` or `reasoning` fields.

**Sources.** `allow` groups `{title, domains[]}` in tiers; `block` proxies and mirrors; `prioritize` and `avoid` as text; say discovery pages are never the citation. Not readable: LinkedIn, Instagram, TikTok, X, Facebook, Reddit profiles and feeds, Glassdoor, Zillow, login-walled marketplaces. Use an Extract Template where one exists.

**Batching.** Enrichment: hard cap ≤20 rows and ≤200 cells (rows × fields) per run; practical batch is about 5 rows for 6 researched fields at `high`, 10 rows for 2 or 3 fields. Rows beyond the budget come back with only their input values and the run still says completed. Dataset building: scope each run to 50 to 100 rows by region or category. Research: one entity per run. Account defaults: 30 concurrent, 200 runs per day.

**Completion.** `completed` means finished. Check rows returned vs asked, cell fill, and open a sample of citations. The confidence grade is a sort key derived from fill and citation presence, not a verification. Keep a ledger keyed on your identifier; dedupe after merge; resubmit misses with completed rows as an exclusion list in `input_data`. Treat a run active for more than 30 minutes as lost and resubmit once.

## Minimal working example

```python Python theme={"system"}
from nimble_python import Nimble
import time

nimble = Nimble(api_key="YOUR-API-KEY")

run = nimble.agents.run(
    agent_name="eu-ai-infra-enricher",
    use_case="enrichment",
    effort="high",
    skill=("You are a B2B research analyst completing company records. For each row, read the "
           "company's own site first, then press and filings. Never infer; set null when no public "
           "page states a value. Constrain person fields to the row's own domain."),
    goals=["Every non-null value has a public source on the row's own domain or a dated press page",
           "Return exactly one row per input row, in input order"],
    input="Fill the missing fields for the companies in input_data.",
    input_data=[{"company": "Qdrant", "domain": "qdrant.tech"},
                {"company": "Weaviate", "domain": "weaviate.io"}],
    output_schema={
        "type": "array",                       # a list in input_data needs an array root
        "items": {"type": "object",
            "required": ["company", "domain"],
            "properties": {
                "company": {"type": "string"},
                "domain": {"type": "string"},
                "employee_band": {"type": ["string", "null"], "enum": ["1-10", "11-50", "51-200", "201-1000", "1000+", None],
                                  "description": "Headcount band from the company's site or a dated press release. Null if none."},
                "ceo_name": {"type": ["string", "null"], "description": "Current CEO as named on an official page. Null if not published."},
                "ceo_source_url": {"type": ["string", "null"], "description": "URL of the page naming the CEO."}
            }}},
)

agent_id = run.web_search_agent_id
while run.is_active:
    time.sleep(15)
    run = nimble.agents.runs.get(run.id, agent_id=agent_id)

if run.status == "completed":
    result = nimble.agents.runs.result(run.id, agent_id=agent_id)
    rows = result.output.content
    assert len(rows) == 2, f"expected 2 rows, got {len(rows)}"
```

## Next Steps

> **[MCP Server](https://docs.nimbleway.com/integrations/mcp-server)**
>
> Call agents from Claude, Cursor and other MCP clients

> **[Plugin installation](https://docs.nimbleway.com/integrations/agent-skills/plugin-installation.md)**
>
> Nimble skills for coding agents

> **[API Reference](https://docs.nimbleway.com/api-reference/introduction.md)**
>
> Every field and response


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.