For Coding 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

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

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

Call agents from Claude, Cursor and other MCP clients

Plugin installation

Nimble skills for coding agents

API Reference

Every field and response

Getting Started

Search Tools

Agent

Extraction Tools

Extract Template

Extract Jobs

Guides

SDKs

Admin

Proxy

Setup prompt

Endpoints

Rules

Minimal working example

Next Steps

MCP Server

Plugin installation

API Reference

​Setup prompt

​Endpoints

​Rules

​Minimal working example

​Next Steps

MCP Server

Plugin installation

API Reference

Setup prompt

Endpoints

Rules

Minimal working example

Next Steps