Biomimicry research

Expansive Biomimicry Research Agent

agents.biomimicry.expansive_research

Launches a long-running biomimicry research job that builds a broad portfolio of biological strategy records for a functional challenge. It is designed for discovery, early R&D, education, regenerative design, and downstream synthesis workflows where breadth, citations, and mechanism detail matter more than immediate lookup speed.

POST /v1/agents/agents.biomimicry.expansive_research/invokeagents:invoke

When to use it

Good fit

Generating many candidate biological strategies, not a single best answer.
Creating a structured portfolio with organism or system, function, mechanism, abstract design principle, confidence, source mix, and citation fields.
Starting innovation, design, curriculum, or research workflows with enough breadth for later filtering or synthesis.
Running background research jobs that can be polled or completed by webhook.
Controlling breadth, source mix, recency, continuation behavior, and budget from the caller side.

Use something else when

Known-item lookup, typeahead, image search, or a small set of existing records. Use lighter search endpoints for those jobs.
Low-latency user interactions that must return final research content immediately.
Engineering validation, regulatory review, clinical advice, or feasibility proof.
Blind retries of long-running POST requests after client timeouts. Store and poll the returned job when you have one.

Use when a workflow needs a broad, cited portfolio of biological strategy records before filtering, synthesis, education, design review, or downstream recommendation.

Required inputs

session_id: Caller-chosen session label for this research run. Use it for correlation and resume flows; do not treat it as a guaranteed idempotency key.
design_challenge: Functional challenge and operating context to research. Strong inputs describe what must be achieved, where, and under what constraints.

Optional inputs

initial_functions: Seed functional paths to explore. Use this to broaden or constrain the search space.
focus_organisms: Organisms or ecosystems to prioritize when you already have biological hunches.
target_strategy_count: Target portfolio size. Verified range: 10 to 500; default: 200.
confidence_threshold: Minimum confidence for adding a strategy. Verified range: 0 to 10; default: 0.5.
curated_source_percentage: Target percentage of strategies from curated biomimicry records before leaning more heavily on literature. Verified range: 0 to 100; default: 50.
recency_constraint: Optional source-age requirement shaped as max_years and min_percentage.
resource_recency_target: Portfolio-level target from 0.0 to 1.0 for recent source coverage.
resource_recency_years: Defines what counts as recent for resource_recency_target. Verified range: 1 to 20; default: 5.
bootstrap_from_similar: Reuse useful strategy records from related prior sessions when available. Default: true.
bootstrap_max_age_months: Maximum age of related sessions considered for reuse. Verified range: 1 to 24; default: 6.
max_continuation_loops: Continuation loops allowed before returning a capped result. Verified range: 0 to 5; default: 1.
resume_from_session: Session ID to continue from when resuming a known research run.
max_cost_usd: Budget guard. Public calls apply the approved endpoint ceiling when omitted, and values above that ceiling are clamped before the job is queued.
configuration.webhook_url: Optional HTTPS URL to receive completion or failure events.
configuration.webhook_secret: Optional secret used by your system to verify webhook signatures.
configuration.metadata: Caller-owned metadata returned for your workflow correlation.

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.biomimicry.expansive_research.
poll_url: Relative polling URL for the job result.
estimated_cost_usd: Preflight estimate returned when the job is accepted.
created_at / completed_at: Job lifecycle timestamps when available.
result.session_id: Session label used for this research run.
result.status: Agent-level outcome such as completed, paused, continuation_limit_reached, budget_limit_reached, or error.
result.strategy_count / target_count: Returned or saved strategy count and requested strategy target.
result.average_confidence: Average confidence across returned strategies.
result.source_mix_breakdown: Counts by public source category. Treat these as portfolio texture, not proof of source quality.
result.functions_covered: Functions represented in the returned strategy set.
result.organisms_referenced: Organisms or biological systems represented in the returned strategy set.
result.strategies_above_threshold: Strategies meeting the configured confidence threshold.
result.curated_sources_exhausted: Whether the curated-source path was exhausted during research.
result.academic_papers_searched: Count of literature records searched.
result.papers_with_full_text / papers_abstract_only: Counts that help reviewers understand evidence depth.
result.continuation_count / can_continue / continuation_summary: Continuation state for capped or resumable runs.
result.citation_count: Total public citations attached across the result.
result.recency_constraint_applied: Whether recency_constraint shaped the run.
result.recent_articles_percentage: Share of dated sources that met the recency constraint, when available.
result.articles_with_known_dates / articles_with_unknown_dates: Source-date coverage for recency interpretation.
result.bootstrap_strategies_selected: Strategy records reused from related prior sessions.
result.curated_source_mix_applied / curated_source_percentage_target: Whether the source-mix setting was applied and which target was used.
result.curated_strategies_count / literature_strategies_count: Counts on each side of the requested source mix.
result.resource_recency_*: Portfolio-level recency settings, counts, percentage, and target-met signal.
result.strategies / final_strategies: Strategy records. Some runs may emit a separate finalized set.
result.warnings: Builder-facing warnings, when present.
result.charge_usd: Customer-visible charge for a billable completed job.

Strategy record fields

id: Opaque strategy identifier. Do not infer structure from its format.
name: Short strategy name.
function: Function the strategy addresses.
organism_or_system: Source organism, ecosystem, or biological system.
written_strategy: Grounded biological observation. It should preserve the organism or system and what it does in nature.
mechanism: Explanation of how and why the biological strategy works.
adp: Abstract design principle for human application. This may intentionally remove biological wording.
scale: Two-number range from 1 to 10, where [1, 10] means broad or unknown scale.
is_pattern / is_algorithm: Signals for repeated biological patterns or process-like strategies.
confidence: Relevance, evidence, and mechanism-quality signal on a 0 to 10 scale. It is not proof of feasibility.
depth_score / feasibility_score / innovation_score: Supporting review signals for evidence depth, translation difficulty, and novelty.
source_type / source_id: Source category and opaque source identifier such as a DOI, PMID, URL, or record ID.
citation / bibliographic_citation: Short and fuller citation strings when available.
abstract_only: True when only abstract-level evidence was available. Review these with extra care.
url / doi / pmid / publication_year: Public source fields when known.
nuance_notes / nuance_issue_type: Additional review notes when a strategy needs caution or refinement.
citations / citation_count: Public citation objects and count attached to this strategy.

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.
Creates or resumes a named research session so saved strategies can survive long runs, continuation stops, or budget stops.
Starts from design_challenge, then uses initial_functions and focus_organisms when supplied to shape the search space.
Can reuse useful strategy records from related prior sessions when bootstrap_from_similar is enabled.
Balances curated biomimicry knowledge and scientific literature according to curated_source_percentage, saturation, and recency controls.
Extracts strategy records with biological observation, mechanism, abstract design principle, scale, confidence, quality scores, source fields, and citation fields.
Saves strategies as they are found so partial results can still be useful when status is budget_limit_reached, paused, or continuation_limit_reached.
Returns the completed agent output under result and includes charge_usd when the completed call is billable.

Trust and caution

A strategy record is a candidate, not a final recommendation.
written_strategy is the grounded biological observation and should preserve the organism or system.
mechanism explains how the biological strategy works.
adp is the abstract design principle for human application and may intentionally remove biological wording.
confidence blends relevance, evidence support, and mechanism clarity. It does not mean the strategy is validated for your specific design context.
abstract_only true means the record needs extra review before high-stakes use.
source_mix_breakdown and source count fields help you evaluate breadth and evidence mix, not truth.
Generated abstractions can overgeneralize. Preserve written_strategy and mechanism beside adp so reviewers can check the biological grounding.
Use expert review, primary-source review, prototyping, and domain-specific validation for high-stakes applications.

Runtime

This is a long-running asynchronous research endpoint. Small jobs may finish in minutes; broad portfolios can take much longer. Show queued or running state and poll with backoff until the job is completed or failed.

Cost behavior

Cost varies with target_strategy_count, source mix, recency settings, continuation settings, and budget. Use estimated_cost_usd for preflight display and charge_usd from the completed result for final customer-visible accounting.

Billing notes

The queued response includes estimated_cost_usd as a preflight estimate.
inputs.max_cost_usd is a budget guard. Public calls apply the approved endpoint ceiling when omitted, and values above that ceiling are clamped before the job is queued.
Requests can fail before queuing with insufficient_credits if the account cannot cover the estimated call.
Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
Organization credits are deducted for billable completed work according to the account's public API pricing.
Budget-limited and continuation-limited results can still be useful portfolios, but they should be labeled as partial in your product.

Representative input

{
  "inputs": {
    "session_id": "cooling-schools-2026-05",
    "design_challenge": "Passive cooling for low-cost schools in hot, dry climates",
    "initial_functions": [
      "Reject solar heat",
      "Move heat away from occupied spaces",
      "Store coolness overnight"
    ],
    "target_strategy_count": 60,
    "curated_source_percentage": 50,
    "resource_recency_target": 0.4,
    "resource_recency_years": 8,
    "max_cost_usd": 3.0
  },
  "configuration": {
    "webhook_url": "https://example.com/webhooks/agent-ecology",
    "webhook_secret": "whsec_...",
    "metadata": {
      "project_id": "proj_123",
      "workflow_step": "research"
    }
  }
}

Queued response

{
  "job_id": "job_7f3a2b1c",
  "status": "queued",
  "agent_id": "agents.biomimicry.expansive_research",
  "estimated_cost_usd": 3.6,
  "created_at": "2026-05-27T18:30:00Z",
  "poll_url": "/v1/jobs/job_7f3a2b1c"
}

Representative completed result

{
  "job_id": "job_7f3a2b1c",
  "status": "completed",
  "agent_id": "agents.biomimicry.expansive_research",
  "created_at": "2026-05-27T18:30:00Z",
  "completed_at": "2026-05-27T18:52:14Z",
  "result": {
    "session_id": "cooling-schools-2026-05",
    "status": "completed",
    "strategy_count": 60,
    "target_count": 60,
    "average_confidence": 7.1,
    "source_mix_breakdown": {
      "scientific_literature": 31,
      "curated_sources": 29
    },
    "functions_covered": [
      "Reject solar heat",
      "Move heat away from occupied spaces"
    ],
    "organisms_referenced": [
      "Saharan silver ant",
      "termite mound",
      "desert snail"
    ],
    "citation_count": 55,
    "strategies": [
      {
        "id": "strategy_001",
        "name": "Reflective body hairs",
        "function": "Reject solar heat",
        "organism_or_system": "Saharan silver ant",
        "written_strategy": "Saharan silver ants use triangular body hairs that strongly reflect visible and near-infrared light while helping emit thermal radiation.",
        "mechanism": "The hair geometry creates optical scattering and thermal emission effects that reduce heat gain under intense sun.",
        "adp": "Use geometry-tuned surface fibers to reflect incoming radiation while preserving outward heat emission.",
        "scale": [2, 4],
        "confidence": 8.2,
        "depth_score": 8.0,
        "feasibility_score": 6.5,
        "innovation_score": 7.5,
        "source_type": "academic_paper",
        "source_id": "10.0000/example",
        "citation": "Author et al., 2024",
        "bibliographic_citation": "Author et al. (2024). Example study title.",
        "abstract_only": false,
        "url": "https://doi.org/10.0000/example",
        "doi": "10.0000/example",
        "pmid": null,
        "publication_year": 2024,
        "citations": [
          {
            "title": "Reflective body hairs",
            "doi": "10.0000/example",
            "pmid": null,
            "url": "https://doi.org/10.0000/example",
            "in_text": "Author et al., 2024",
            "full": "Author et al. (2024). Example study title.",
            "year": 2024,
            "open_access": false
          }
        ],
        "citation_count": 1
      }
    ],
    "charge_usd": 2.74
  }
}

Errors and retries

Common failures

400: required inputs.session_id or inputs.design_challenge is missing, numeric ranges are invalid, or the JSON shape is wrong.
401: the API key is missing or invalid.
402: the account does not have enough credits or billing setup for the estimated call.
403: the key does not have agents:invoke scope or the agent is not available to the caller.
429: the client exceeded the allowed request rate.
503: the platform could not accept or complete the research job at that time.
failed: the accepted job could not complete, often because input validation, research extraction, continuation, or billing could not complete.
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}; polling is the safe recovery path.
Honor Retry-After on 429 responses.
Do not blindly retry POST /invoke after a network timeout because the public contract does not currently include an idempotency key.
Store job_id and poll_url as soon as they are returned so the client can recover after refreshes or network interruptions.
Use webhooks for production workflows that should not depend on long client polling windows.
If result.status is budget_limit_reached, paused, or continuation_limit_reached, inspect the saved strategies before deciding whether to continue.

Composition ideas

Research then distill

Invoke expansive research, poll for completion, then send selected strategies to a synthesis, scoring, or distillation step.

Background research copilot

Launch the endpoint from an assistant, store job_id and poll_url, and return later with a summary once polling or webhook completion succeeds.

Evidence dashboard

Display strategy_count, source_mix_breakdown, average_confidence, citation_count, abstract_only flags, and charge_usd for review.

Budgeted exploration presets

Offer conservative, balanced, and broad presets by adjusting target_strategy_count, curated_source_percentage, recency controls, and max_cost_usd.

Curriculum builder

Group strategies by function, organism_or_system, confidence, and scale so learners can compare biological mechanisms and abstractions.

Webhook workflow

Submit the job with configuration.webhook_url and configuration.metadata, then resume your workflow when completion arrives.

Application fit

Early-stage product discovery and concept workshops.
Materials, packaging, robotics, architecture, and climate adaptation R&D.
Regenerative design workflows and ecosystem-inspired planning.
Education modules where students compare mechanisms, evidence quality, and design abstractions.
Innovation-team research assistants that create portfolios for later review.
Knowledge browsing interfaces that pivot from strategies into organisms, functions, citations, and images.
Content research for exhibits, articles, explainers, and design reports.
Evaluation datasets for testing downstream summarizers, distillers, and recommendation agents.

Back to agent catalog