Quickstart

Every Web Search Agent task follows the same three steps: create a run, wait for it to complete, and retrieve the result. This page walks through the full loop. You need an API key from the Nimble Platform and a client:

pip install nimble_python

npm install @nimble-way/nimble-js

go get github.com/Nimbleway/nimble-go@latest

npm install -g @nimble-way/nimble-cli
export NIMBLE_API_KEY="YOUR-API-KEY"

Create a run

Send the task in plain language. agents.run generates an agent with default settings (research mode, high effort) and starts the run asynchronously:

from nimble_python import Nimble

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

run = nimble.agents.run(
    input=(
        "Compare the pricing and positioning of Datadog, Grafana Cloud, "
        "and New Relic for a mid-size SaaS team."
    ),
)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

const run = await nimble.agents.run({
  input:
    "Compare the pricing and positioning of Datadog, Grafana Cloud, " +
    "and New Relic for a mid-size SaaS team.",
});

package main

import (
    "context"
    "fmt"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(option.WithAPIKey("YOUR-API-KEY"))
    ctx := context.Background()

    run, err := client.Agents.Run(ctx, nimble.AgentRunParams{
        Input: "Compare the pricing and positioning of Datadog, Grafana Cloud, " +
            "and New Relic for a mid-size SaaS team.",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(run.ID, run.Status)
}

RUN=$(nimble agents run \
  --input "Compare the pricing and positioning of Datadog, Grafana Cloud, and New Relic for a mid-size SaaS team.")

RUN_ID=$(echo "$RUN" | jq -r .id)
AGENT_ID=$(echo "$RUN" | jq -r .web_search_agent_id)

curl -X POST 'https://sdk.nimbleway.com/v2/agents/runs' \
  --header 'Authorization: Bearer <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "Compare the pricing and positioning of Datadog, Grafana Cloud, and New Relic for a mid-size SaaS team."
  }'

The response contains the run id and the generated agent’s id. Both are needed to poll and fetch the result:

{
  "id": "task_run_01j9x8...",
  "web_search_agent_id": "wsa_01j9x8...",
  "status": "queued",
  "is_active": true,
  "effort": "high",
  "created_at": "2026-07-22T10:15:00Z"
}

Add an output_schema to the request to get structured JSON back instead of prose. See Dataset Building.

Wait for completion

Poll while is_active is true. Alternatively, create the run with enable_events: true and stream GET .../runs/{run_id}/events as server-sent events:

import time

agent_id = run.web_search_agent_id

while run.is_active:
    time.sleep(10)
    run = nimble.agents.runs.get(run.id, agent_id=agent_id)
print(run.status)  # completed

const agentId = run.web_search_agent_id;

let polled = run;
while (polled.is_active) {
  await new Promise((r) => setTimeout(r, 10000));
  polled = await nimble.agents.runs.get(run.id, { agent_id: agentId });
}
console.log(polled.status); // completed

for run.IsActive {
    time.Sleep(10 * time.Second)
    polled, err := client.Agents.Runs.Get(ctx, run.ID, nimble.AgentRunGetParams{
        AgentID: run.WebSearchAgentID,
    })
    if err != nil {
        panic(err)
    }
    run.IsActive = polled.IsActive
}

nimble agents:runs get --agent-id "$AGENT_ID" --run-id "$RUN_ID"
# repeat while "is_active" is true

curl "https://sdk.nimbleway.com/v2/agents/$AGENT_ID/runs/$RUN_ID" \
  --header 'Authorization: Bearer <YOUR-API-KEY>'

Retrieve the result

result = nimble.agents.runs.result(run.id, agent_id=agent_id)

print(result.output.content)             # the answer
print(result.output.trust.confidence)    # high / medium / low
for claim in result.output.trust.claims:
    print(claim.citations[0].url)        # sources behind each claim

const result = await nimble.agents.runs.result(run.id, { agent_id: agentId });

if ("output" in result) {
  console.log(result.output.content);          // the answer
  console.log(result.output.trust.confidence); // high / medium / low
  for (const claim of result.output.trust.claims) {
    console.log(claim.citations[0].url);       // sources behind each claim
  }
}

result, err := client.Agents.Runs.Result(ctx, run.ID, nimble.AgentRunResultParams{
    AgentID: run.WebSearchAgentID,
})
if err != nil {
    panic(err)
}
fmt.Println(result.Output.Content.OfString) // the answer
fmt.Println(result.Output.Trust.Confidence) // high / medium / low

nimble agents:runs result --agent-id "$AGENT_ID" --run-id "$RUN_ID"

curl "https://sdk.nimbleway.com/v2/agents/$AGENT_ID/runs/$RUN_ID/result" \
  --header 'Authorization: Bearer <YOUR-API-KEY>'

The output contains the answer and its trust report:

Datadog anchors the premium end of the market, with Pro pricing from
$15 per host per month [1]. Grafana Cloud undercuts it with a free
tier and usage-based pricing [2], positioning itself for teams that
want to start small...

Every [n] maps to a claim in trust.claims, with source URLs, verbatim excerpts, and a confidence grade. See Trust.

Fetching the result while the run is still active returns 409 — keep polling. A failed run returns 422 with error details.

Run lifecycle

Status	Meaning
`queued`	Accepted, waiting to start
`running`	The agent is working — `is_active` is `true`
`completed`	The result is ready at `.../result`
`failed`	The run stopped with an error — `.../result` returns `422` with details
`cancelled`	The run was stopped before completion

Follow-up runs

Every run carries an interaction_id. Pass it as previous_interaction_id on the next run to continue the same task with full context — a follow-up question, a refinement, or a drill-down:

followup = nimble.agents.runs.create(
    agent_id,
    input="Now break down the enterprise tiers only.",
    previous_interaction_id=run.interaction_id,
)

const followup = await nimble.agents.runs.create(agentId, {
  input: "Now break down the enterprise tiers only.",
  previous_interaction_id: run.interaction_id,
});

followup, err := client.Agents.Runs.New(ctx, agentID, nimble.AgentRunNewParams{
    Input:                 "Now break down the enterprise tiers only.",
    PreviousInteractionID: param.NewOpt(run.InteractionID),
})

nimble agents:runs create \
  --agent-id "$AGENT_ID" \
  --input "Now break down the enterprise tiers only." \
  --previous-interaction-id "$INTERACTION_ID"

curl -X POST "https://sdk.nimbleway.com/v2/agents/$AGENT_ID/runs" \
  --header 'Authorization: Bearer <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "Now break down the enterprise tiers only.",
    "previous_interaction_id": "'$INTERACTION_ID'"
  }'

Create a persistent agent

agents.run generates a one-off agent with default settings. For recurring tasks, create a persistent agent with a skill, goals, sources, and a default effort. A persistent agent keeps its memory across runs and improves over time:

agent = nimble.agents.create(
    display_name="SaaS Pricing Watcher",
    skill="SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages.",
    goals=[
        "Compare pricing tiers with plan names and price ranges",
        "Call out pricing changes announced in the last quarter",
    ],
    sources={
        "prioritize": "official vendor pricing pages over third-party summaries",
        "block": [{"title": "Aggregators", "domains": ["g2.com"]}],
    },
    effort="x-high",
)

const agent = await nimble.agents.create({
  display_name: "SaaS Pricing Watcher",
  skill: "SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages.",
  goals: [
    "Compare pricing tiers with plan names and price ranges",
    "Call out pricing changes announced in the last quarter",
  ],
  sources: {
    prioritize: "official vendor pricing pages over third-party summaries",
    block: [{ title: "Aggregators", domains: ["g2.com"] }],
  },
  effort: "x-high",
});

agent, err := client.Agents.New(ctx, nimble.AgentNewParams{
    DisplayName: param.NewOpt("SaaS Pricing Watcher"),
    Skill:       param.NewOpt("SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages."),
    Goals: []string{
        "Compare pricing tiers with plan names and price ranges",
        "Call out pricing changes announced in the last quarter",
    },
    Sources: nimble.AgentNewParamsSources{
        Prioritize: param.NewOpt("official vendor pricing pages over third-party summaries"),
        Block: []nimble.AgentNewParamsSourcesBlock{
            {Title: "Aggregators", Domains: []string{"g2.com"}},
        },
    },
    Effort: nimble.AgentNewParamsEffortXHigh,
})

nimble agents create \
  --display-name "SaaS Pricing Watcher" \
  --skill "SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages." \
  --goal "Compare pricing tiers with plan names and price ranges" \
  --goal "Call out pricing changes announced in the last quarter" \
  --sources '{prioritize: "official vendor pricing pages over third-party summaries", block: [{title: "Aggregators", domains: ["g2.com"]}]}' \
  --effort x-high

curl -X POST 'https://sdk.nimbleway.com/v2/agents' \
  --header 'Authorization: Bearer <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "SaaS Pricing Watcher",
    "skill": "SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages.",
    "goals": [
      "Compare pricing tiers with plan names and price ranges",
      "Call out pricing changes announced in the last quarter"
    ],
    "sources": {
      "prioritize": "official vendor pricing pages over third-party summaries",
      "block": [{"title": "Aggregators", "domains": ["g2.com"]}]
    },
    "effort": "x-high"
  }'

Next Steps

Trust

Per-claim citations and confidence grades

Use Cases

Research, Enrichment, and Dataset Building

API Reference

Every endpoint, field, and response

Getting Started

Web Tools

Extract Templates

Web Search Agents

Jobs

Guides

SDKs

Admin

Proxy

Run lifecycle

Follow-up runs

Create a persistent agent

Next Steps

Trust

Use Cases

API Reference

​Run lifecycle

​Follow-up runs

​Create a persistent agent

​Next Steps

Trust

Use Cases

API Reference

Run lifecycle

Follow-up runs

Create a persistent agent

Next Steps