---
title: AI Orchestration
description: >-
  Submit computational biology jobs using natural language with automatic AI
  routing to the right tools.
tags:
  - orchestration
  - ai
  - natural-language
  - routing
---

AI orchestration lets you describe a drug discovery task in plain English and have the CLI pick the right tools, extract parameters, and run them for you. Reach for it when you don't want to remember exact tool names or parameter syntax, or when a request spans several tools in one step. It runs on the same backend and job history as the rest of the CLI, so orchestrated jobs are monitored and downloaded just like any other. For the full command set, see the [CLI overview](/docs/cli).

  beginner

## AI Orchestration _(since v0.8.10)_
Submit computational biology jobs using natural language with automatic AI routing to the right tools.

---

## Overview

The `orchestrate` command lets you describe what you want in plain English. An AI model interprets your request, selects the appropriate tools, and executes them:

|AI intent detection| B["'esmfold' selected"]
    B -->|Parameter extraction| C["protein_sequence = insulin sequence"]
    C -->|Tool execution| D["Job submitted → job_abc123"]`}
  caption="A plain-English request is interpreted into a tool, its parameters, and a submitted job."
/>

This is the simplest way to use ivybloom — no need to know tool names or parameter syntax.

---

## Usage

```bash
# Basic: natural language request
ivybloom orchestrate "Predict the structure of insulin"

# Multi-step request
ivybloom orchestrate "Run ADMET on aspirin and ibuprofen"

# Restrict the tools it may call
ivybloom orchestrate "Dock caffeine against 1ABC" --tools diffdock

# Override the AI model
ivybloom orchestrate "Explain BRCA1 druggability" --model MODEL_ID
```

- `PROMPT` (string) —
Natural language description of your request (positional argument, quoted).

- `--model` (string) —
Override the AI model used for intent detection and routing.

- `--tools` (string) —
Restrict available tools (comma-separated). Example: `--tools esmfold,diffdock`.

- `--output` (string) —
Output format: `text`, `json`, or `yaml` (`-o` shorthand).

- `--preflight` (bool) —
Run health check before orchestration.

- `--stateless` (bool) —
Run one turn with no session persistence (for evaluation and CI).

---

## Examples

### Single Tool Invocation

```bash
# Protein folding
ivybloom orchestrate "Fold BRCA1"

# ADMET prediction
ivybloom orchestrate "Check drug-likeness of aspirin"

# Molecular docking
ivybloom orchestrate "Dock erlotinib into EGFR binding site"
```

### Multi-Step Requests

The orchestrator can chain multiple tools in a single request:

```bash
# Fold, then find binding sites
ivybloom orchestrate "Fold EGFR, find its binding sites, and dock erlotinib"

# Screen multiple compounds
ivybloom orchestrate "Screen aspirin, ibuprofen, and caffeine for drug-likeness"
```

### Restricted Tool Set

Limit the orchestrator to specific tools for predictable behavior:

```bash
# Only allow folding and docking
ivybloom orchestrate "Analyze this protein" --tools esmfold,diffdock
```

---

## Headless Mode

Root flags provide quick single-message interactions without the TUI:

```bash
# Single headless message
ivybloom -m "Fold BRCA1"

# Wait for job completion
ivybloom -m "Fold BRCA1" --follow

# Structured JSON output for scripting
ivybloom -m "Fold BRCA1" --agent
```

> For CI/CD automation, combine `-m` with `--agent` for structured JSON output. See [Agent Mode](/docs/cli/agent-mode) for the full envelope schema.

---

## Streaming

Stream partial text output as the AI generates its response. `--stream-partial-output` is a root flag, so use it with `-m`:

```bash
ivybloom -m "Explain the mechanism of EGFR inhibition" --stream-partial-output
```

This is useful for long explanatory responses where you want to see output incrementally.

---

## AI Model Selection

The orchestrator uses the default AI model from your config. You can override it per-request:

```bash
# Use a specific model
ivybloom orchestrate "Fold BRCA1" --model claude-3-opus

# Check available models
ivybloom config models list
```

### Model Pricing

How a model choice affects credit spend is covered in [plans and tiers](/docs/plans-and-tiers#how-the-platform-meters-and-gates).

See [Billing & Credits](/docs/cli/billing) for cost details and [Configuration](/docs/cli/configuration) for BYOK setup.

---

## Output Formats

**Text (default)**

```
I'll fold the BRCA1 protein sequence using ESMFold.

Job submitted: job_abc123
Tool: esmfold
Status: running

The structure prediction is in progress. You can monitor it with:
  ivybloom jobs follow job_abc123
```

**JSON**

```
{
  "response": "I'll fold the BRCA1 protein sequence using ESMFold.",
  "tool_calls": [
    {
      "tool": "esmfold",
      "job_id": "job_abc123",
      "status": "running",
      "parameters": {
        "protein_sequence": "MDLSALREVE..."
      }
    }
  ]
}
```

**YAML**

```
response: "I'll fold the BRCA1 protein sequence using ESMFold."
tool_calls:
  - tool: esmfold
    job_id: job_abc123
    status: running
    parameters:
      protein_sequence: "MDLSALREVE..."
```

---

## Read next

- [MCP Integration](/docs/cli/mcp) — Full tool catalog for AI agents
- [Batch Processing](/docs/cli/batch) — Run parallel jobs for screening
- [Job Management](/docs/cli/jobs) — Monitor and download job results
- [Billing & Credits](/docs/cli/billing) — Understand model costs