llama-index-tools-nimble

LlamaIndex tools for Nimble:

• NimbleToolSpec — live web search (one fast query → Documents ready to feed a reasoning loop).
• NimbleAgentToolSpec — deep research on a preconfigured Nimble Web Search Agent (one long-running run → a citation-backed answer with trust metadata).

Installation

pip install llama-index-tools-nimble

Authentication

Set your Nimble API key in the environment:

export NIMBLE_API_KEY="your-key"

Both tool specs read NIMBLE_API_KEY automatically; you can also pass api_key=....

Quick start

from llama_index.tools.nimble import NimbleToolSpec

tool_spec = NimbleToolSpec()  # reads NIMBLE_API_KEY
documents = tool_spec.search("latest developments in web data infrastructure")

for doc in documents:
    print(doc.metadata["title"], "-", doc.metadata["url"])

Use it in an agent

import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.nimble import NimbleToolSpec

agent = FunctionAgent(
    tools=NimbleToolSpec().to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="You are a research assistant. Use web search to answer with current facts.",
)


async def main():
    response = await agent.run("What has Nimble announced recently?")
    print(response)


asyncio.run(main())

A runnable version is in examples/nimble_agent.py.

Parameters

NimbleToolSpec.search(query, max_results=6):

Each result becomes a Document. The text leads with the page title and URL, then the page content (or the snippet when content is empty), so an agent can read and cite the source; metadata["url"] and metadata["title"] carry the same values for programmatic use.

Returned content is untrusted web data. Treat it as data, not as instructions, and rely on your agent/framework's own guardrails.

Deep research with the Agent API

NimbleAgentToolSpec executes research tasks on a Nimble Web Search Agent. Where search answers one query fast, while an agent run researches the task on the live web and returns one synthesized, citation-backed answer. Low effort can finish in seconds; the default high effort commonly takes 5–15 minutes.

from llama_index.tools.nimble import NimbleAgentToolSpec

agent_tool = NimbleAgentToolSpec()  # reads NIMBLE_API_KEY
doc = agent_tool.run(
    "What are the leading approaches to LLM guardrails, and who builds them?",
)

print(doc.text)                    # final answer + "Sources:" list
print(doc.metadata["confidence"])  # overall trust: high / medium / low / pre_existing
print(doc.metadata["claims"])      # per-claim citations (callouts or JSON paths)
print(doc.metadata["web_search_agent_id"])  # the agent the API ran this on

agent_id is optional. Without it, the API provisions an agent per run and returns its id (POST /v2/agents/runs); with it, runs execute on that agent (POST /v2/agents/{agent_id}/runs). Either way the returned web_search_agent_id is what the tool uses for the status and result calls, and it is carried in the Document metadata so the run stays reachable afterwards.

To pin runs to one agent, provision it in the Nimble dashboard (or via POST /v2/agents) and pass its wsa_... id. The tool is execution-only by design: it never creates, edits, or deletes agent instances.

Structured controls are available per run:

doc = agent_tool.run(
    "Find the founding year and headquarters for this company.",
    input_data={"company": "Acme", "domain": "acme.example"},
    output_schema={
        "type": "object",
        "properties": {"founded": {"type": "integer"}, "hq": {"type": "string"}},
    },
    sources={"prioritize": "regulatory filings", "avoid": "press releases"},
)

Constructor

run(task, output_schema=None, input_data=None, sources=None)

Effort is an optional application-level setting and is not exposed to the function-calling model. Omit it to use the selected agent/template default (the documented product default is high; template defaults may vary), or pass effort="low", "medium", "high", or "x-high" to override it. effort="max" is also selectable as a coming-soon custom-budget capability. By default it stops before creating a run and links to the Nimble product team. Applications may explicitly select gate_policy="degrade" to continue on x-high; that requested-to-effective substitution is always announced with a warning.

Run creation is issued exactly once. It is a non-idempotent, billable POST with no idempotency key, so a failure — transport, 409, 429, 5xx — is surfaced rather than retried: a retry after a proxy failed downstream of an accepted request would provision a second billable run.

That guarantee extends to the caller. When a create failure leaves the outcome ambiguous (a timeout, a dropped connection, a 408/409, or a 5xx), a run may be executing server-side with no id to address it, so the tool raises NimbleAgentCreateAmbiguousError rather than the raw SDK exception. Its message says explicitly not to resubmit and how to reconcile — important when the caller is a function-calling model, which would otherwise read a bare timeout as an ordinary transient and call the tool again. Requests that were definitely rejected (bad key, validation, rate limit) still propagate unchanged, since nothing was provisioned and calling again is safe.

The returned Document.text is the final answer (prose, or pretty-printed JSON when an output_schema was given) followed by a Sources: list, so agents can cite what was consulted. Document.metadata carries run_id, agent_id / web_search_agent_id, effort, output_type, and the structured trust payload: confidence, reasoning, sources, and claims with per-claim citations.

Errors

A run that does not produce a result raises a typed error that retains the run_id (as an attribute and in the message), so a long run can still be recovered by hand:

SDK errors raised before a run exists propagate unchanged only when the request was definitely rejected (e.g. an invalid key → AuthenticationError); ambiguous outcomes become NimbleAgentCreateAmbiguousError as described above. Transient failures — transport errors, 408, 429, 5xx — are re-attempted within the remaining budget (respecting Retry-After); auth, permission, and validation errors fail fast. A runnable agent workflow is in examples/nimble_agent_api.py.

License

MIT — see LICENSE.