Function discovery

Multifunctional Search Agent

agents.multifunctional_search

Turns project context into related biological design functions, searches for biological strategies that can satisfy those functions together, and returns a narrative synthesis plus structured groups and candidate strategy records.

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

When to use it

Good fit

Design briefs, transcript excerpts, product challenges, site observations, or research questions that contain several needs or constraints.
Extracting two to six useful biological functions before searching for strategy candidates.
Exploring multifunctional needs such as protection, sensing, transport, recovery, moisture control, thermal comfort, coordination, or signaling.
Building classroom tools, research assistants, workshop boards, product discovery copilots, and biomimicry exploration interfaces.
Rendering both a readable summary and structured fields that can drive cards, lanes, filters, or follow-on calls.

Use something else when

Proof that a biological strategy is technically, medically, legally, or commercially ready to apply.
An exhaustive survey of all biology relevant to a function.
Exact record lookup when you already know the specific item you need.
Private, regulated, or sensitive user content unless your own application is authorized to process that content through the API.
Assuming every candidate has complete citation coverage. Some results are useful leads rather than fully cited evidence packets.

Use near the beginning of a larger workflow, before deeper literature review, image selection, evidence gathering, strategy distillation, or workshop synthesis.

Required inputs

session_id: Caller-provided run or project identifier. Use a stable value when connecting this result to the rest of your workflow.
context: Project context, transcript excerpt, challenge notes, product constraints, workshop notes, or research question.

Optional inputs

challenge_summary: Short label for the design challenge.
focus_area: A narrower area to emphasize, such as impact recovery, moisture management, signaling, thermal comfort, or coordination.
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.multifunctional_search.
poll_url: Relative polling URL for the job result.
estimated_cost_usd: Pre-run estimate for planning. The final billed amount can differ.
created_at / completed_at: Job lifecycle timestamps when available.
result.session_id: Echoes the caller-provided session_id.
result.summary: Narrative synthesis of the extracted functions and biological leads.
result.functions_searched: Function phrases the agent used for discovery.
result.adaptation_count: Count of candidate adaptations represented in the result.
result.function_groups: Structured groups that can become UI lanes, comparison sections, or follow-on workflow inputs.
result.final_responses: Shortlisted biological strategy records for downstream review.
result.charge_usd: Customer-visible charge for a billable completed job.

Result card fields

function_groups[].result_ids: Candidate response IDs associated with the group. Use these to connect columns, cards, filters, or follow-on selections.
final_responses[].score: Relevance signal for search fit. It is not a truth score, feasibility score, safety rating, or evidence grade.
final_responses[].response_names: Available response labels that can help users understand why the candidate was included.
final_responses[].matched_function_groups: Group IDs that explain where a candidate fits in the extracted function structure.

How output is produced

Authenticates the API key and confirms permission to invoke agents.
Checks whether the account can start a billable discovery 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.
Treats the submitted context as source material and looks for stated needs, constraints, failure modes, operating conditions, and tradeoffs.
Identifies a small set of biological design functions that the project appears to need together.
Searches for biological strategies that connect more than one extracted function instead of only matching a single keyword.
Adds strategy, organism, relevance, and source context when useful details are available.
Returns a narrative summary plus structured function groups and candidate response records for downstream interfaces.

Trust and caution

This endpoint is a discovery aid. It helps find promising biological analogies, but it does not prove feasibility.
Treat function_groups as useful framing for exploration. They may need editing for your domain vocabulary.
Treat final_responses as leads for deeper review, not final engineering recommendations.
Treat functions_searched as an explanation of the discovery path, not a guarantee that every possible function was searched.
Citation coverage depends on the available source context for each candidate.
Vague or overly broad context can produce broad function groups. More concrete constraints usually produce more useful results.
Use expert review for engineering, medical, safety, legal, financial, conservation, or other high-impact decisions.

Runtime

Treat this endpoint as asynchronous. The invoke call returns quickly, but completion can take longer because the agent may extract functions, run several discovery passes, gather supporting detail, and synthesize a response. Show queued, running, completed, and failed states in your UI.

Cost behavior

Use estimated_cost_usd from the queued response for pre-run display and charge_usd from the completed result for final customer-visible accounting. Budget for variable completion time and cost based on context length and the number of useful biological leads found.

Billing notes

The queued response includes estimated_cost_usd as a pre-run estimate.
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.
The final charge can be lower or higher than the pre-run estimate depending on context length, extracted functions, and candidate evidence gathered.

Representative input

{
  "inputs": {
    "session_id": "run_packaging_001",
    "context": "Reusable containers need to protect glass components during repeated shipping cycles, avoid moisture buildup, recover after drops, and make damage easy to spot before reuse.",
    "challenge_summary": "Protect fragile goods in reusable shipping containers",
    "focus_area": "impact recovery and inspection"
  },
  "configuration": {
    "metadata": {
      "external_run_id": "packaging-001",
      "workflow_step": "function_discovery"
    }
  }
}

Queued response

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

Representative completed result

{
  "job_id": "job_7f3a2b1c",
  "agent_id": "agents.multifunctional_search",
  "status": "completed",
  "created_at": "2026-05-27T18:30:00Z",
  "completed_at": "2026-05-27T18:32:41Z",
  "result": {
    "session_id": "run_packaging_001",
    "summary": "The context points to linked functions: absorb impact, recover after deformation, manage moisture, and reveal damage before reuse. Biological leads suggest layered structures that redirect cracks, reversible deformation strategies, surfaces that move moisture away from sensitive zones, and visible cues that indicate structural change. Treat these as research leads for deeper source review and prototype translation.",
    "functions_searched": [
      "absorb sudden mechanical energy",
      "restore shape after deformation",
      "move moisture away from protected contents",
      "signal damage before reuse"
    ],
    "adaptation_count": 3,
    "function_groups": [
      {
        "id": "fg_impact_recovery",
        "group_id": "fg_impact_recovery",
        "name": "absorb and recover from impact",
        "functions": [
          "absorb sudden mechanical energy",
          "restore protective geometry after deformation"
        ],
        "result_ids": [
          "resp_layered_deflection"
        ]
      }
    ],
    "final_responses": [
      {
        "id": "resp_layered_deflection",
        "name": "Layered crack deflection",
        "title": "Layered crack deflection",
        "summary": "Layered interfaces can redirect cracks and preserve overall structure, making them useful leads for reusable protective packaging.",
        "score": 0.87,
        "response_names": [
          "crack deflection through layered interfaces"
        ],
        "response_instance_count": 2,
        "matched_function_groups": [
          "fg_impact_recovery"
        ]
      }
    ],
    "charge_usd": 0.146
  }
}

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.
400: webhook_url is not HTTPS in production.
429: the client exceeded the allowed request rate.
503: the platform could not accept or complete the discovery job at that time.
failed: the accepted job could not complete, often because required input was missing, the context was unusable, a long search timed out, or billing could not be completed.
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.
Use the returned poll_url rather than resubmitting the same request immediately.
Retry transient 503 responses only when no job_id was returned, and use caller-side safeguards to prevent duplicate submissions.
Use a stable session_id and your own metadata when you need idempotent workflow behavior.
If the result feels generic, ask the user for more concrete constraints instead of repeating the same request.

Composition ideas

Search-to-research pipeline

Call this endpoint first, let users select a function group or final response, then send the selected lead into a deeper research or evidence review step.

Workshop board

Map function_groups to columns and final_responses to cards. Add voting, notes, and manual edits before deeper analysis.

Education workflow

Ask students to compare the returned functions with their own framing, then verify one candidate against primary sources.

Product discovery copilot

Use the result as planning state for a larger assistant. The assistant can ask follow-up questions when context is vague or when scores are close.

Batch portfolio review

Run briefs one at a time, then compare functions_searched across jobs to identify recurring opportunity areas.

Application fit

Design education studio assistants that turn student briefs into function groups and biological leads.
Early product discovery tools that convert messy constraints and failure modes into research directions.
Workshop facilitation boards that cluster breakout notes into functions participants can vote on.
Curriculum generators that compare how organisms solve protection, sensing, transport, repair, and coordination.
Regenerative design exploration tools for places, buildings, landscapes, and organizations.
Knowledge browsing interfaces that connect function groups to deeper biological records and article views.
AI copilots that call this endpoint early, then pass selected candidates to research, image, or strategy agents.
Innovation portfolio scanners that compare recurring function families across product or program briefs.

Back to agent catalog