> ## 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.
# Omnigent
> Omnigent ships three Nimble capabilities: a web_search provider, Extract Templates for structured scraping, and Agent API V2 for cited deep research.
## Overview
[Omnigent](https://github.com/omnigent-ai/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](/nimble-sdk/web-tools/search) | `web_search` with `search_provider: nimble` | Grounded live web results for any model | Seconds |
| [Extract Template](/nimble-sdk/web-tools/extract/template) | `nimble_extract` builtin | Runs one of your account's templates, returns structured JSON | Seconds |
| [Web Search Agent](/nimble-sdk/web-search-agents/overview) | `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
The `nimble_extract` and `nimble_research` builtins first shipped in 0.9.0. Earlier releases carry only the `web_search` provider.
The only credential any of the three capabilities needs. Get one from the [dashboard](https://online.nimbleway.com/settings/api-keys). Every request Omnigent sends carries `X-Client-Source: omnigent`.
`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
```bash theme={"system"}
# 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:
```bash theme={"system"}
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](/nimble-sdk/web-tools/search). 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.
```bash theme={"system"}
export NIMBLE_API_KEY="your-api-key"
```
A custom agent lives in its own directory with a `config.yaml` at the root. Create `research-agent/config.yaml`:
```yaml research-agent/config.yaml theme={"system"}
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}
```
```bash theme={"system"}
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
**Required.** Set to `nimble` to route web search through Nimble.
**Required.** Your Nimble API key. Use `${NIMBLE_API_KEY}` to read it from the environment instead of hardcoding it in the spec.
**Optional.** Number of results to return, from `1` to `100`. Defaults to `5`. Values outside the range are clamped.
**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](/nimble-sdk/web-tools/search-depth) for details.
A fully configured provider looks like this:
```yaml theme={"system"}
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](/nimble-sdk/web-tools/extract/template) 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.
```yaml research-agent/config.yaml theme={"system"}
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`:
```bash theme={"system"}
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`:
```bash theme={"system"}
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
**Required.** Your Nimble API key.
**Required.** The name of one of your account's extract templates.
**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](/nimble-sdk/web-tools/extract/template).
## Deep research
`nimble_research` runs a research task on a [Web Search Agent](/nimble-sdk/web-search-agents/overview) 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.
```yaml research-agent/config.yaml theme={"system"}
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](/nimble-sdk/web-search-agents/efforts) 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.
**Required.** The research task or question.
Optional. One of `low`, `medium`, `high`, or `x-high`. Omit it to use the agent or template default. The product default is [`high`](/nimble-sdk/web-search-agents/efforts), and template defaults vary.
Optional run mode. Exactly one of `research`, `enrichment`, or `dataset_building`.
Optional records to enrich: a JSON object, or an array of JSON objects, passed to the agent as input.
Optional JSON schema requesting structured output instead of prose.
Optional source guidance: `prioritize`, `avoid`, and `allow` or `block` groups of `{ title, domains, order? }`.
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](/nimble-sdk/web-search-agents/efforts) 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
**Required.** Your Nimble API key.
Optional. A Web Search Agent you own, in the form `wsa_...`. Omit it to have Nimble provision one per run.
Optional overall deadline. Defaults to `300`, clamped to `10` to `3600`. Raise it: the default is shorter than a typical run.
Optional interval between status polls. Defaults to `10`, clamped to `0.5` to `30`.
### Run an agent
```bash theme={"system"}
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:
```json theme={"system"}
{
"run_id": "task_run_",
"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_`.
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](/nimble-sdk/web-search-agents/overview) directly if you need them.
## Additional Resources
The open-source agent framework and meta-harness.
Define and run a custom agent: directory layout, `config.yaml`, and the run command.
The Search endpoint behind the `web_search` provider.
Browse, run, and generate templates for popular websites.
The deep-research capability behind `nimble_research`.
The full Databricks integration: Marketplace MCP, Genie, and SQL-native enrichment.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.