Source-aware research

Adaptive Search Instrument

agents.adaptive_search_instrument

Runs bounded web and citation-oriented research around a focused question. It returns cited answer groups, deduplicated source cards, partial-error reporting, and a source strategy value that lets builders tune discovery for speed, breadth, or citation emphasis.

POST /v1/agents/agents.adaptive_search_instrument/invokeagents:invoke

When to use it

Good fit

  • Gathering current source candidates before a report, brief, article, lesson, assistant response, or review workflow is drafted.
  • Running quick landscape scans for companies, markets, technologies, policy topics, scientific themes, design opportunities, or emerging fields.
  • Collecting cited answer groups that a reviewer or downstream provenance tool can inspect before publication.
  • Building research assistants that need source cards, answer snippets, partial-error reporting, and a clear separation between discovery and verification.
  • Refreshing a knowledge base or dashboard with recent external signals while preserving a review step.

Use something else when

  • Treating returned answer text as verified truth. Use it as discovery material that still needs review.
  • Final legal, medical, financial, safety, or other high-stakes advice.
  • Assuming every citation fully supports every sentence. Use a provenance check for claim-level support.
  • Very broad one-word queries when strong results require context, time range, source expectations, and domain terms.
  • Full-text archiving. Full text retrieval, storage, and reuse require separate product and rights controls.

Use when a workflow needs current source discovery before synthesis, review, evidence collection, or knowledge-base enrichment.

Required inputs

query
Focused research question or search task. Include domain, timeframe, geography, evidence expectations, and intended use when those details matter.

Optional inputs

source_strategy
`fast`, `balanced`, `broad`, or `citation_focused`. Defaults to `balanced`. Use `fast` for lightweight orientation, `broad` for wider coverage, and `citation_focused` when reviewable sources matter most.
mode
`quick`, `deep`, or `citation`. Defaults to `quick`, except `citation_focused` defaults to citation mode when mode is omitted.
limit
Maximum number of deduplicated source results to return. Defaults to `10`; supported range is `1..20`.
configuration.metadata
Caller-owned metadata for connecting the job to a workflow, review queue, dashboard, or webhook receiver.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id
Identifier used to poll GET /v1/jobs/{job_id}.
status
Job state, such as queued, running, completed, or failed.
agent_id
The invoked agent, here agents.adaptive_search_instrument.
poll_url
Relative polling URL for the job result.
estimated_cost_usd
Preflight estimate used before the job runs. The final charge can differ.
result.success
Whether the research step completed with usable output.
result.query
Echoed research query.
result.mode
Mode used for the search.
result.limit
Maximum deduplicated result count requested.
result.source_strategy
Source selection strategy used by the agent.
result.source_groups[]
Answer groups with stable IDs, answer text, matching sources, and result counts.
result.sources[]
Deduplicated sources across answer groups.
result.results[]
Deduplicated source cards for UI rendering, review, or downstream processing.
result.result_count
Number of source cards returned.
result.errors
Partial research-channel errors when some work failed but other work succeeded.
result.charge_usd
Customer-visible amount charged for the completed public API call when billing applies.

Result card fields

source_groups[].answer
Synthesized answer text, often with inline source markers. Treat it as orientation until reviewed.
source_groups[].sources
Sources corresponding to the answer group. Keep these visible in review interfaces.
results[].score
Ranking signal for ordering returned source cards. It is not a truth, confidence, or importance score.

How output is produced

  • Authenticates the API key and confirms permission to invoke agents.
  • Checks whether the account can start a billable research job before work begins.
  • Accepts the request as an asynchronous job and returns job_id, status, agent_id, poll_url, estimated_cost_usd, and created_at.
  • Reads the query, mode, source_strategy, limit, and optional caller metadata.
  • Chooses available research channels that fit the requested strategy and mode.
  • Runs selected research channels concurrently so a workflow can gather several perspectives without waiting for each one in sequence.
  • Keeps synthesized answer groups paired with their source arrays, deduplicates source records where possible, and preserves partial errors instead of discarding successful output.
  • Returns source_strategy, source_groups, sources, results, result_count, errors, and charge_usd when the completed job is billable.

Trust and caution

  • The endpoint is a discovery tool, not a claim verifier.
  • Returned citations are not the same as claim-level proof.
  • Source freshness and coverage depend on available research channels and query wording.
  • Scores are ranking signals, not truth or confidence values.
  • Review sources before high-stakes use, external publication, customer delivery, or automated decision-making.
  • Do not store or reuse third-party source content beyond what your rights and product policy allow.

Runtime

Treat this endpoint as asynchronous. A typical integration should show queued or running state, poll with backoff, and render the completed result when status becomes completed.

Cost behavior

The queued response includes estimated_cost_usd for display or logging before completion. Use charge_usd from the completed result for final customer-visible accounting.

Billing notes

  • The queued response includes estimated_cost_usd as a preflight estimate.
  • Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
  • Quick mode is usually the lowest-latency option. Deep and citation modes can do more work and may cost more.
  • Use limit to keep UI payloads compact. Do not treat limit as a complete cost ceiling.
Representative input
{
  "inputs": {
    "query": "passive daytime radiative cooling materials for building envelopes, prioritize 2024-2026 review sources",
    "source_strategy": "citation_focused",
    "mode": "citation",
    "limit": 8
  },
  "configuration": {
    "metadata": {
      "workflow_id": "research-brief-482",
      "topic": "radiative-cooling"
    }
  }
}
Queued response
{
  "job_id": "a9f0a1d4ce5d4d2dbb2c6df4b1111111",
  "status": "queued",
  "agent_id": "agents.adaptive_search_instrument",
  "poll_url": "/v1/jobs/a9f0a1d4ce5d4d2dbb2c6df4b1111111",
  "estimated_cost_usd": 0.14,
  "created_at": "2026-05-27T02:20:00Z"
}
Representative completed result
{
  "job_id": "a9f0a1d4ce5d4d2dbb2c6df4b1111111",
  "agent_id": "agents.adaptive_search_instrument",
  "status": "completed",
  "created_at": "2026-05-27T02:20:00.000000+00:00",
  "started_at": "2026-05-27T02:20:01.000000+00:00",
  "completed_at": "2026-05-27T02:20:18.000000+00:00",
  "result": {
    "success": true,
    "query": "passive daytime radiative cooling materials for building envelopes, prioritize 2024-2026 review sources",
    "mode": "citation",
    "limit": 8,
    "source_strategy": "citation_focused",
    "source_groups": [
      {
        "id": "source_group_1",
        "answer": "Recent review sources describe passive daytime radiative cooling coatings as a promising route for reducing roof and facade heat gain [1].",
        "sources": [
          {
            "title": "Review of passive daytime radiative cooling materials",
            "url": "https://example.org/radiative-cooling-review",
            "snippet": "Review article discussing cooling coatings and building applications."
          }
        ],
        "result_count": 1
      }
    ],
    "sources": [
      {
        "title": "Review of passive daytime radiative cooling materials",
        "url": "https://example.org/radiative-cooling-review",
        "snippet": "Review article discussing cooling coatings and building applications.",
        "source_group_ids": ["source_group_1"]
      }
    ],
    "results": [
      {
        "title": "Review of passive daytime radiative cooling materials",
        "summary": "Review article discussing cooling coatings and building applications.",
        "url": "https://example.org/radiative-cooling-review",
        "score": 1.0,
        "source_type": "web",
        "source_group_id": "source_group_1"
      }
    ],
    "result_count": 1,
    "errors": null,
    "charge_usd": 0.028
  }
}

Errors and retries

Common failures

  • 401: the API key is missing or invalid.
  • 403: the key does not have agents:invoke scope or the agent is not available to the caller.
  • 402: the account does not have enough credits to start the job.
  • 422: query, mode, source_strategy, or limit failed validation.
  • 429: the client exceeded the allowed request rate.
  • 503: the platform could not accept or complete the research job at that time.
  • completed with errors: some research channels failed but successful answers or source cards are still present.
  • 404: the job ID is wrong, expired, or not owned by the caller.

Retry guidance

  • After a job_id is returned, poll GET /v1/jobs/{job_id} with bounded exponential backoff.
  • Honor Retry-After on 429 responses.
  • For partial errors, show successful results and offer a deliberate retry action rather than discarding the whole response.
  • Retry transient 503 responses only when no job_id was returned, and use caller-side safeguards to prevent duplicate submissions.
  • Do not blindly retry POST /invoke after a network timeout because the public contract does not currently include an idempotency key.

Composition ideas

Search then verify

Run citation-focused search, let users or automation select claims and sources, then pass those pairs into a provenance checker before publication.

Search then summarize

Use source cards and answer groups as curated input for a summary agent, while keeping citations visible outside the summary.

Search then enrich a knowledge base

Use deduplicated source records to identify new or changed public evidence, then route accepted sources into a separate curation workflow.

Search then compare

Run focused queries for adjacent concepts, markets, organisms, technologies, or policies, then compare the returned source sets.

Application fit

  • Research preflight before synthesis.
  • Citation discovery for generated reports.
  • Market and competitor scans.
  • Scientific or technical source discovery.
  • Educational source packs.
  • Knowledge-base refresh.
  • Dashboard enrichment with recent external context.
  • Assistant toolchains that need source-aware retrieval before answering.