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 and output schema limits.

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'"
  }'

Reuse an agent by name

Passing no identity to agents.run (as in Step 1) creates a fresh, disposable agent on every call, no memory carries over between runs. Add agent_name to get a stable, reusable agent without a separate create step: the first call with a new name creates the agent, every later call with the same name routes to it.

run = nimble.agents.run(
    agent_name="saas-pricing-watcher",
    input="Compare the pricing and positioning of Datadog and Grafana Cloud.",
)

# Later calls with the same name reuse the same agent and its memory.
followup = nimble.agents.run(
    agent_name="saas-pricing-watcher",
    input="Now check New Relic too.",
)

const run = await nimble.agents.run({
  agent_name: "saas-pricing-watcher",
  input: "Compare the pricing and positioning of Datadog and Grafana Cloud.",
});

// Later calls with the same name reuse the same agent and its memory.
const followup = await nimble.agents.run({
  agent_name: "saas-pricing-watcher",
  input: "Now check New Relic too.",
});

nimble agents run \
  --agent-name "saas-pricing-watcher" \
  --input "Compare the pricing and positioning of Datadog and Grafana Cloud."

curl -X POST 'https://sdk.nimbleway.com/v2/agents/runs' \
  --header 'Authorization: Bearer <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_name": "saas-pricing-watcher",
    "input": "Compare the pricing and positioning of Datadog and Grafana Cloud."
  }'

use_case and skill can be set the same way, on the call that creates the agent:

run = nimble.agents.run(
    agent_name="saas-pricing-watcher",
    input="Compare the pricing and positioning of Datadog and Grafana Cloud.",
    use_case="research",
    skill="SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages.",
)

const run = await nimble.agents.run({
  agent_name: "saas-pricing-watcher",
  input: "Compare the pricing and positioning of Datadog and Grafana Cloud.",
  use_case: "research",
  skill: "SaaS pricing analyst: compare tiers, flag recent changes, cite vendor pages.",
});

use_case is locked once the agent exists: a later run against the same agent must either omit use_case or pass the value it already has, a different value returns 422. skill, sources, and output_schema work the other way, they stay overridable per run (see below) even after the agent is created.

Create a persistent agent

agents.run without agent_name generates a one-off agent with default settings. For full control over an agent’s lifecycle, create a persistent agent explicitly with a skill, goals, sources, and a default effort — equivalent to what agent_name does implicitly above, but you own the agent_id yourself instead of addressing the agent by name. 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"
  }'

Override per run vs. persist

Once an agent exists (via agent_name or an explicit agent_id), a run can pass sources, output_schema, and skill to override that agent’s defaults for that run only, the agent’s own stored config is unchanged. To persist a change instead, update the agent directly with agents.update(agent_id, ...). use_case doesn’t follow this pattern: it’s fixed once the agent is created, not overridable per run.

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

Search

Web Search Agent

Extraction Tools

Extract Template

Extract Jobs

Guides

SDKs

Admin

Proxy

Run lifecycle

Follow-up runs

Reuse an agent by name

Create a persistent agent

Override per run vs. persist

Next Steps

Trust

Use Cases

API Reference

​Run lifecycle

​Follow-up runs

​Reuse an agent by name

​Create a persistent agent

​Override per run vs. persist

​Next Steps

Trust

Use Cases

API Reference

Run lifecycle

Follow-up runs

Reuse an agent by name

Create a persistent agent

Override per run vs. persist

Next Steps