Public workflow API

Build with Agent Ecology workflows

Agent Ecology Studio exposes a workflow-oriented API for products that need biomimicry-rooted research, concept discovery, knowledge graph lookup, image selection, and expert synthesis. The public surface is built around a small set of specialized agents plus search and knowledge routes that compose into longer product workflows.

Base URL: https://api.agentecology.comVersion: /v1Auth: X-API-Key or Authorization: Bearer

What is in this surface

The workflow API has two kinds of capability. Agent routes run expert processes that may take minutes and produce structured outputs. Search and knowledge routes return records or candidate records immediately for discovery, filtering, and detail views.

Agents

Specialized processes for research, distillation, taxonomy normalization, living-system curation, image work, and synthesis.

Jobs

API-key agent calls are async. You receive a job ID, then poll or receive a terminal webhook event.

Knowledge routes

Concept and field routes support semantic discovery, exact text lookup, detail views, and related-concept exploration.

Async lifecycle

Public API-key calls to agent routes are asynchronous: invoke an agent, store the returned job ID, then poll or receive a terminal webhook event. The first response confirms acceptance only; the final agent output is in the completed job result.

1

Invoke

POST an agent-specific input body.

2

Accepted

Receive 202 with job_id and poll_url.

3

Run

The expert process executes in the background.

4

Handoff

Poll or receive webhook, then persist results.

Invoke
curl https://api.agentecology.com/v1/agents/agents.biomimicry.expansive_research/invoke \
  -X POST \
  -H "X-API-Key: ae_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "User-Agent: your-product/1.0" \
  -d '{
    "inputs": {
      "session_id": "run_packaging_001",
      "design_challenge": "Protect reusable shipping containers from impact while using less material",
      "initial_functions": ["dissipate force", "recover shape"],
      "target_strategy_count": 40,
      "max_cost_usd": 2
    },
    "configuration": {
      "metadata": {
        "workflow_id": "wf_2026_05_26_packaging",
        "step": "expansive_research"
      }
    }
  }'
202 Accepted
{
  "job_id": "8f4c2e5b9a16487abf07b78d5b87d0b3",
  "status": "queued",
  "agent_id": "agents.biomimicry.expansive_research",
  "poll_url": "/v1/jobs/8f4c2e5b9a16487abf07b78d5b87d0b3",
  "estimated_cost_usd": 0.12,
  "created_at": "2026-05-26T17:30:00Z"
}
Poll
curl https://api.agentecology.com/v1/jobs/8f4c2e5b9a16487abf07b78d5b87d0b3 \
  -H "X-API-Key: ae_live_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "User-Agent: your-product/1.0"
Completed job
{
  "job_id": "8f4c2e5b9a16487abf07b78d5b87d0b3",
  "agent_id": "agents.biomimicry.expansive_research",
  "status": "completed",
  "created_at": "2026-05-26T17:30:00Z",
  "started_at": "2026-05-26T17:30:03Z",
  "completed_at": "2026-05-26T17:37:18Z",
  "result": {
    "status": "completed",
    "strategy_count": 42,
    "source_mix_breakdown": {
      "curated_knowledge": 27,
      "scientific_literature": 15
    },
    "charge_usd": 0.34
  }
}

There is no public idempotency-key contract yet for invoke requests. If a network failure happens before you receive a job ID, use your own request ledger before retrying so the same user action does not create duplicate billable jobs.

Public workflow agents

These agents are easiest to understand as a workflow: extract functions, expand research, distill patterns, normalize living systems, select or collect images, and synthesize the result for a reader. You can use them independently, but their outputs are designed to hand off cleanly.

Open agent catalog
1

Executive Summary

Executive synthesis

agents.executive_summary

Turns structured project, research, evaluation, or workflow notes into a concise executive-ready summary. It accepts seven named source sections, generates an overview, extracts key insights, and recommends focus areas for next steps.

2

Adaptive Search Instrument

Source-aware research

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.

3

Multifunctional Search Agent

Function discovery

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.

4

Living Systems Search

Biological system discovery

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.

5

Material Mapper

Building-flow mapping

agents.ecoservices.material_mapper

Maps a design strategy into extracted materials, building metabolism flows, connected ecosystem services, relevant building roles, place-aware opportunity gaps, and system/role/stage lenses. It is built for early design review, educational exploration, circularity workflows, and ecosystem-service framing before a team commits to detailed engineering or procurement decisions.

6

Expansive Biomimicry Research Agent

Biomimicry research

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.

7

Strategy Distiller Agent

Research synthesis

agents.biomimicry.strategy_distiller

Compresses a larger set of submitted biomimicry strategy records into a smaller, reviewable set of biology-language strategy families. It preserves source_strategy_ids, organisms, citations, and mechanism nuance so downstream builders can move from synthesis back to the source records.

8

Taxonomy Normalizer Agent

Biological name normalization

agents.validation.taxonomy_normalizer

Normalizes messy organism, taxon, and functional-group names into reviewable workflow data. It preserves original submitted names, explains merge and keep decisions, flags ambiguous cases, and returns compact hierarchy context for downstream use.

9

Living Systems Curator API

Knowledge curation

agents.biomimicry.living_systems

Creates, updates, or reuses living-system records from a bounded curation task. It is useful when a workflow has identified organisms or biological systems and needs stable IDs for later search, image selection, reporting, education, product discovery, or knowledge review.

10

Living System Image Selector

Image and media selection

agents.biomimicry.living_system_image_selector

Selects the best available image for a known living-system record from existing linked images and curated catalog candidates. The response preserves source, license, license URL, and attribution metadata when a suitable image is available, or returns a normal pending_collection state when image coverage still needs curation.

11

Living System Image Collector

Image and media coverage

agents.biomimicry.living_system_image_collector

Finds, screens, and links candidate images for a known living-system record. It is built for image coverage maintenance: callers provide a living_system_id, collection limits, and optional job metadata; the completed job returns accepted images, rejected counts, rejection reasons, provenance fields, and charge_usd.

Search versus knowledge lookup

Use semantic search when wording is loose and the user is exploring. Use text search when the user knows the phrase. Use concept detail after a user or workflow has selected a concept ID.

Semantic search

Best for discovery, candidate lists, and natural-language questions. Scores rank retrieval fit, not truth.

Text lookup

Best for exact or near-exact wording, autocomplete, and deterministic review flows.

Detail by ID

Best after discovery, when your UI needs stable concept detail and field context.

Open search and knowledge guide

Common composition patterns

These are not product-specific recipes. They are the common ways builders combine the pieces once they understand what each route returns.

Discovery to research

  • Search fields and concepts to help a user clarify the problem language.
  • Invoke multifunctional search to extract functions from broader context.
  • Invoke expansive research when the challenge and functions are clear.

Research to curated output

  • Run expansive research to gather strategy records.
  • Run strategy distiller to compress the strategy set into reviewable patterns.
  • Use related concepts to add cross-domain context around selected principles.

Organism to media

  • Normalize organism names before storing or linking records.
  • Create or reuse living-system records.
  • Select an image; collect images only when coverage is missing or weak.

Agent catalog

What each agent does, when to use it, required inputs, sample requests, and representative results.

Search and knowledge

Semantic concept search, field search, text lookup, detail by ID, and related concepts.

Production use

Webhooks, idempotency, retries, rate limits, error shapes, and cost behavior.