Omnigent

Overview

A Databricks-hosted agent in Omnigent running grounded web search through Nimble

Omnigent is an open-source AI agent framework and meta-harness from Databricks. It gives you one orchestration layer over Claude Code, Codex, Cursor, Pi, and agents you write yourself, with shared sessions, policies, and sandboxing. Omnigent ships three separate Nimble capabilities. They are different products, not settings of one product.

Capability	Omnigent name	What it does	Latency
Search	`web_search` with `search_provider: nimble`	Grounded live web results for any model	Seconds
Extract Template	`nimble_extract` builtin	Runs one of your account’s templates, returns structured JSON	Seconds
Web Search Agent	`nimble_research` builtin	Autonomous research run with per-claim citations	Minutes

Pick web_search to ground an answer, nimble_extract when you have a template for a known site shape, and nimble_research when the question needs many sources and an auditable answer.

Prerequisites

Omnigent 0.9.0 or later

The nimble_extract and nimble_research builtins first shipped in 0.9.0. Earlier releases carry only the web_search provider.

A Nimble API key

The only credential any of the three capabilities needs. Get one from the dashboard. Every request Omnigent sends carries X-Client-Source: omnigent.

The nimble extra, for nimble_research only

nimble_research calls Nimble through the nimble-python client, which ships in the optional nimble extra. nimble_extract and web_search call the API over HTTP and need no extra.

Install

# uv
uv pip install 'omnigent[nimble]'

# pip
pip install --pre 'omnigent[nimble]'

Two details in that command matter. Keep the quotes. Shells such as zsh expand unquoted square brackets, so pip install omnigent[nimble] fails before pip runs. pip needs --pre. Omnigent depends on opentelemetry-instrumentation-fastapi, which publishes only pre-release versions. pip skips pre-releases by default, finds nothing that satisfies the requirement, and gives up with ResolutionImpossible. --pre allows them. uv accepts a pre-release automatically when it is the only thing published, so it needs no flag.

Installing without the extra still succeeds. The Nimble client is imported lazily, so a base install fails on the first nimble_research call rather than at install time. nimble_extract and web_search keep working.

Confirm both builtins resolve from the installed release:

python -c "from omnigent.tools.builtins import nimble_research, nimble_extract; print('ok')"

Web search

Nimble is a first-class web_search provider. Set search_provider: nimble in any agent spec and the agent gets grounded, live web results from Nimble’s Search API. No fork, no plugin. Omnigent lets you run any model and swap harnesses with a one-line change. Nimble brings that same flexibility to web search: one model-agnostic backend with anti-bot handling, JS rendering, and geo-targeting underneath. Databricks-hosted models get grounded web search out of the box.

Export your API key

export NIMBLE_API_KEY="your-api-key"

Enable the provider

A custom agent lives in its own directory with a config.yaml at the root. Create research-agent/config.yaml:

research-agent/config.yaml

spec_version: 1
name: research-agent
prompt: |
  You are a research assistant. Use web_search to ground your
  answers in current information from the web.

executor:
  type: omnigent
  model: databricks-claude-sonnet-4-6   # run on any model

tools:
  builtins:
    - name: web_search
      search_provider: nimble
      api_key: ${NIMBLE_API_KEY}

Run the agent

omni run ./research-agent -p "What were the biggest AI model releases this month?"

The agent now calls Nimble whenever it searches the web.

Web search configuration

search_provider

Required. Set to nimble to route web search through Nimble.

api_key

Required. Your Nimble API key. Use ${NIMBLE_API_KEY} to read it from the environment instead of hardcoding it in the spec.

max_results

Optional. Number of results to return, from 1 to 100. Defaults to 5. Values outside the range are clamped.

search_depth

Optional. Controls the speed-versus-richness tradeoff. Defaults to lite.

lite: titles, URLs, and snippets. Lowest latency, best for broad discovery.
deep: full real-time page extraction for each result. Higher latency, richer content.

See Search Depth for details.

A fully configured provider looks like this:

tools:
  builtins:
    - name: web_search
      search_provider: nimble
      api_key: ${NIMBLE_API_KEY}
      max_results: 10
      search_depth: deep

Extract Template

nimble_extract runs one of your account’s Extract Templates with a single synchronous call to POST /v2/extract/templates/run, and returns the template’s structured, parsed results as JSON. Templates are account-scoped. Each one declares its own input schema, and the model supplies a matching params object on every call.

research-agent/config.yaml

tools:
  builtins:
    - name: nimble_extract
      api_key: ${NIMBLE_API_KEY}
      template: google_search    # one of your account's templates
      # optional:
      # timeout_seconds: 120

The model then calls the tool with the template’s parameters, for example {"query": "nimbleway"}.

Find your templates

List the templates your account can reach. The response is paginated, with total, limit, and offset alongside items:

curl -H "Authorization: Bearer $NIMBLE_API_KEY" \
  'https://sdk.nimbleway.com/v2/extract/templates?limit=20'

Then fetch one by name to see the params it accepts. The input schema sits at published_version.input_schema:

curl -H "Authorization: Bearer $NIMBLE_API_KEY" \
  https://sdk.nimbleway.com/v2/extract/templates/google_search \
  | jq '.published_version.input_schema'

Use the required and properties of that schema to see what the model must supply in params.

Extract configuration

api_key

Required. Your Nimble API key.

template

Required. The name of one of your account’s extract templates.

timeout_seconds

Optional. Read timeout for the template run. Defaults to 120, clamped to 10 to 600.

This is the migration target for the deprecated /v1/agent site-scraping path. The former nimble_agent tool name is retired rather than aliased, so it cannot silently resolve to a different API. See Extract Template.

Deep research

nimble_research runs a research task on a Web Search Agent through Agent API V2. The builtin starts a run, polls it to a terminal status, then fetches the cited result. One call can take minutes.

research-agent/config.yaml

tools:
  builtins:
    - name: nimble_research
      api_key: ${NIMBLE_API_KEY}
      timeout_seconds: 900        # set this explicitly, see below
      # optional:
      # agent_id: wsa_...         # omit to let Nimble provision the agent
      # poll_interval_seconds: 10

Set timeout_seconds in every spec. The default of 300 is often shorter than a default-effort run needs, so a spec left on defaults can time out on a perfectly healthy run. Raise it to suit the effort level you use.

Which agent a run uses

agent_id selects the create route.

Omitted: POST /v2/agents/runs. Nimble provisions an agent for the run and returns its ID. No agent has to exist first.
Provided: POST /v2/agents/{agent_id}/runs, against an agent you own.

Either way the response carries both a run ID and a web_search_agent_id. Every later status and result request is addressed to the returned web_search_agent_id, never to the configured agent_id, because on the generic route the returned ID is the only one that exists. If the two are both present and disagree, the call fails rather than guessing which agent to address. The run was still created and billed, so the error carries the run ID for you to reconcile against.

Per-call arguments

The spec configures credentials and timing. The model supplies the rest per call.

task

Required. The research task or question.

effort

Optional. One of low, medium, high, or x-high. Omit it to use the agent or template default. The product default is high, and template defaults vary.

use_case

Optional run mode. Exactly one of research, enrichment, or dataset_building.

input_data

Optional records to enrich: a JSON object, or an array of JSON objects, passed to the agent as input.

output_schema

Optional JSON schema requesting structured output instead of prose.

sources

Optional source guidance: prioritize, avoid, and allow or block groups of { title, domains, order? }.

skill / agent_name

Optional hints forwarded to the run. skill names a skill identifier, agent_name names the run’s agent.

max appears in the tool schema but is a coming-soon custom-budget capability, not a selectable tier. Supplying it stops the call before the run is created, with product-team contact guidance. It is never silently substituted for another effort level.

Spec configuration

api_key

Required. Your Nimble API key.

agent_id

Optional. A Web Search Agent you own, in the form wsa_.... Omit it to have Nimble provision one per run.

timeout_seconds

Optional overall deadline. Defaults to 300, clamped to 10 to 3600. Raise it: the default is shorter than a typical run.

poll_interval_seconds

Optional interval between status polls. Defaults to 10, clamped to 0.5 to 30.

Run an agent

omni run ./research-agent -p "Research the EU AI Act enforcement timeline and cite your sources."

The model calls nimble_research, the builtin drives the run to completion, and the agent answers from a source-grounded result.

What the tool returns

A bounded JSON envelope:

{
  "run_id": "task_run_<uuid>",
  "web_search_agent_id": "wsa_...",
  "status": "completed",
  "output": {
    "type": "text",
    "content": "..."
  },
  "trust": {
    "confidence": "...",
    "reasoning": "...",
    "sources": [{ "url": "...", "type": "...", "title": "..." }],
    "claims": [{ "claim": "...", "confidence": "...", "citations": ["..."] }]
  }
}

output.type is text for prose or json when you passed an output_schema. Run IDs have the form task_run_<uuid>. Run statuses are queued and running while work continues, and completed, failed, or cancelled once terminal. The envelope is capped so a large result cannot exhaust the model’s context: 50,000 characters of content, 10 sources, 10 claims, and 3 citations per claim. Truncation is reported rather than hidden.

Billing and retries

Run creation is billable and not idempotent, and the API exposes no idempotency key. The builtin therefore issues the create call exactly once and never retries it, on any outcome. Retries are confined to the read-only calls: polling retries transport errors, 408, 429, and 5xx, and the result call re-checks only the documented 409. That splits create failures into two classes.

Failure	Billing outcome	What to do
Transport error, timeout, 408, 5xx	Unknown. The request may have reached Nimble.	Do not resubmit. Reconcile against the run ID, or your account’s run history when no ID survived.
401, 403, 404, 422, create-time 429	Nothing was created. A rate limiter refuses the request before a run starts.	Safe to retry.

Once creation succeeds the run exists and is billed, so every later failure carries the same do-not-resubmit guidance, keyed to the run ID.

Event streaming and interaction chaining are not exposed by this builtin. Use the Agent API directly if you need them.

Additional Resources

Omnigent on GitHub

The open-source agent framework and meta-harness.

Omnigent Custom Agents

Define and run a custom agent: directory layout, config.yaml, and the run command.

Nimble Search API

The Search endpoint behind the web_search provider.

Extract Template

Browse, run, and generate templates for popular websites.

Web Search Agent

The deep-research capability behind nimble_research.

Nimble on Databricks

The full Databricks integration: Marketplace MCP, Genie, and SQL-native enrichment.

Agent Skills

MCP Server

Partnerships

Connectors

Proxy

Overview

Prerequisites

Install

Web search

Web search configuration

Extract Template

Find your templates

Extract configuration

Deep research

Which agent a run uses

Per-call arguments

Spec configuration

Run an agent

What the tool returns

Billing and retries

Additional Resources

Omnigent on GitHub

Omnigent Custom Agents

Nimble Search API

Extract Template

Web Search Agent

Nimble on Databricks

​Overview

​Prerequisites

​Install

​Web search

​Web search configuration

​Extract Template

​Find your templates

​Extract configuration

​Deep research

​Which agent a run uses

​Per-call arguments

​Spec configuration

​Run an agent

​What the tool returns

​Billing and retries

​Additional Resources

Omnigent on GitHub

Omnigent Custom Agents

Nimble Search API

Extract Template

Web Search Agent

Nimble on Databricks

Overview

Prerequisites

Install

Web search

Web search configuration

Extract Template

Find your templates

Extract configuration

Deep research

Which agent a run uses

Per-call arguments

Spec configuration

Run an agent

What the tool returns

Billing and retries

Additional Resources