Biological system discovery

Living Systems Search

agents.biomimicry.living_systems_search

Finds organisms and other living systems that match a name, biological function, habitat context, or strategy keyword. It returns structured candidate cards with names, descriptions, functions, strategies, ranking signals, and optional image references.

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

When to use it

Good fit

Building organism search experiences by common name, scientific name, biological function, habitat context, or strategy keyword.
Starting biomimicry exploration from a function such as collect water, regulate temperature, reduce drag, self-clean, or sense change.
Populating organism cards, comparison tables, lesson sets, science-media tools, and nature-inspired design interfaces.
Finding candidate organisms before evidence review, literature search, pattern curation, image selection, or expert synthesis.

Use something else when

Scientific proof by itself. Results are discovery candidates that should be checked against supporting evidence before strong claims are made.
Medical, legal, safety, financial, conservation, engineering, or other high-stakes decisions without expert review.
Exhaustive biodiversity coverage. Recall depends on the current catalog and associated metadata.
Treating ranking scores or image availability as biological importance, truth, or confidence.
Broad one-word queries when your product needs precise matches. Add a function, context, organism group, or strategy phrase.

Use when a product needs candidate organisms or living systems before deeper review, synthesis, image selection, or record lookup.

Required inputs

query: The organism name, function, habitat context, or strategy phrase to search for.

Optional inputs

search_type: One of name, function, habitat, or strategy. Defaults to name when omitted.
filters.kingdoms[]: Limit results to taxonomic kingdoms such as Animalia, Plantae, Fungi, Bacteria, or Protista.
filters.habitats[]: Limit results using habitat terms when habitat metadata or descriptive text supports the match.
filters.has_images: When true, return only results with available image references.
include_images: When true, include image references when available. Defaults to true.
limit: Maximum number of results to return. Use small limits for suggestions and larger limits for exploration. Supported range is 1 to 100.
configuration.webhook_url: Optional HTTPS URL for completion callbacks.
configuration.metadata: Optional caller-owned metadata used to connect callbacks and job records to your local workflow.

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

results[]: Living-system candidate cards returned after filters and limit are applied.
total_found: Returned match count after filtering and limit application.
query: The original submitted query string.
search_type: The mode used for the search.
charge_usd: Customer-visible charge for the completed call when billing applies.

Result card fields

id: Opaque living-system identifier for follow-up lookups.
common_name: Display name for the system.
scientific_name: Scientific name when available.
description: Short public description when available.
kingdom: Taxonomic kingdom when available.
level: Biological level when available.
key_functions[]: Public function labels associated with the system.
habitats[]: Habitat terms when available.
strategies[]: Strategy notes associated with the system.
strategy_count / principle_count: Compact relationship-count signals for richer result cards.
images[]: Optional image references with source and attribution fields when available.
relevance_score: Ranking signal normalized for the returned result set.

How output is produced

Authenticates the API key, accepts the job, and returns a polling handle immediately.
Reads the required query and optional search mode to prioritize name matches, functional analogies, environmental context, or strategy language.
Searches the living-system catalog with text and meaning-based matching so exact names and approximate phrases can both return candidates.
Adds relationship context for function and strategy searches when known associations help connect wording to relevant systems.
Applies caller filters for taxonomic group, habitat terms, image availability, and result limit.
Returns structured candidate cards and customer-visible billing fields through the completed job result.

Trust and caution

Treat returned systems as candidates, not final evidence statements.
A high relevance score means the result ranked well for this query and returned set; it is not a universal truth score.
Relationship-count fields help design richer cards, but they should not be treated as quality scores.
Image coverage is uneven and should not be used as a proxy for biological relevance.
If your UI adds confidence labels, calibrate those labels separately and explain what they mean.
Review generated summaries, strategy notes, and downstream interpretations for high-stakes, regulated, engineering, academic, conservation, or safety use.

Runtime

Usually short, but runtime depends on query breadth, search mode, filters, image inclusion, catalog lookup time, and webhook delivery.

Cost behavior

Use smaller limits for typeahead and interactive card grids, larger limits for exploration, and disable image inclusion when your UI does not need images. Customer-visible billing uses estimated_cost_usd at acceptance and charge_usd after completion.

Billing notes

Billable public API calls return or attach charge_usd. Treat it as the customer-visible charge for the completed call when billing applies.
The queued response can include estimated_cost_usd for display or logging before completion; use charge_usd from the completed result for final customer-visible accounting.
Organization credits are deducted for billable completed work according to the account's configured public API pricing.
Build product UI around the queued estimate and final customer-visible charge.

Representative input

{
  "inputs": {
    "query": "collect water from fog",
    "search_type": "function",
    "filters": {
      "has_images": true
    },
    "include_images": true,
    "limit": 5
  },
  "configuration": {
    "metadata": {
      "workspace_id": "workspace_123",
      "request_id": "local_request_456"
    }
  }
}

Queued response

{
  "job_id": "job_abc123",
  "status": "queued",
  "agent_id": "agents.biomimicry.living_systems_search",
  "poll_url": "/v1/jobs/job_abc123",
  "estimated_cost_usd": 0.01,
  "created_at": "2026-05-26T18:00:00Z"
}

Representative completed result

{
  "job_id": "job_abc123",
  "status": "completed",
  "result": {
    "query": "collect water from fog",
    "search_type": "function",
    "total_found": 2,
    "results": [
      {
        "id": "living_system_example_1",
        "common_name": "Namib Desert Beetle",
        "scientific_name": "Stenocara gracilipes",
        "description": "A desert beetle known for collecting moisture from fog using surface features on its body.",
        "kingdom": "Animalia",
        "level": "organism",
        "key_functions": ["water collection", "moisture capture"],
        "habitats": ["desert"],
        "strategies": [
          "Surface texture helps direct condensed water toward the mouth."
        ],
        "images": [
          {
            "url": "https://example.com/image.jpg",
            "source": "image source",
            "attribution": "creator or collection",
            "is_primary": true
          }
        ],
        "relevance_score": 0.92
      }
    ],
    "charge_usd": 0.01
  }
}

Errors and retries

Common failures

Missing inputs.query.
Unsupported inputs.search_type.
inputs.limit outside the supported range.
filters in an unexpected shape.
Webhook URL missing HTTPS when webhook delivery is configured.
Missing or invalid API key, missing permission to invoke agents, or requested agent unavailable to the caller.
Search job failed before completion, temporary catalog search failure, webhook delivery failure, or expired job result.

Retry guidance

Do not retry validation or permission errors until the request or API key is corrected.
Retry transient failures with exponential backoff and jitter.
For rate limits, wait until the reset time or use the server-provided retry guidance when present.
Store job_id and poll_url so the client can recover after a refresh or network interruption.
Use webhooks for unattended workflows and keep polling as a reconciliation fallback.
If a query returns sparse results, retry with a more specific function, organism group, habitat, or strategy phrase instead of repeating the same request.

Composition ideas

Search-to-card UI

Submit the user query, poll the job result, and render each result as a card with name, description, functions, strategy snippets, ranking signal, and optional image.

Biomimicry ideation funnel

Use a function search to identify candidate organisms, let users select promising systems, then send selections into deeper research or pattern synthesis.

Habitat plus function discovery

Run a habitat search to define local ecological context, then run function searches inside that context to find more relevant biological precedents.

Assistant retrieval tool

Call this endpoint before a conversational assistant answers what organisms solve a particular problem, then ground the answer in returned candidates.

Visual browsing pipeline

Request image references for exploratory browsing, but let users continue without images when strong biological matches have sparse media coverage.

Evidence review chain

Treat returned systems as candidates, then pass selected systems into literature, citation, or expert-review steps before publishing claims.

Application fit

Education products, museums, nature centers, science media, and public learning tools.
Biomimicry ideation interfaces that turn user problems into candidate living systems.
Regenerative design workflows that collect local or analogous biological precedents by function, habitat, or strategy.
Curriculum builders that assemble organism sets for lessons on adaptation, ecology, and nature-inspired design.
Media workflows that need organism candidates plus attribution-ready image references.
AI assistants that need retrieval before deeper synthesis or evidence review.

Back to agent catalog