Agent Usage Guide

Agents should use ABI as a lifecycle control layer rather than writing bioinformatics pipeline code directly.

Getting Started

Install ABI Skills (Claude Code)

abi install-skills

This copies 40 bundled SKILL.md files to ~/.claude/skills/abi/. After installation, Claude Code automatically loads the skills and knows how to use the abi CLI and its bioinformatics tools.

Use --force to overwrite existing files, or --target to customize the destination directory.

Claude Code, OpenCode, and Codex integrations

The repository ships a Claude Code plugin under integrations/claude-code/abi/ an OpenCode configuration plus Agent Skill under integrations/opencode/, and a Codex plugin under integrations/codex/abi/. All three use the same transport-neutral ABI interface and start the MCP server with the default safe profile.

Install ABI with MCP support before loading an integration:

pip install "abi-agent[mcp]"

Use the unified installer for user or project scope:

abi agent install claude-code --scope project
abi agent install opencode --scope project
abi agent install codex --scope project
abi agent doctor codex --scope project

The installer preserves unrelated OpenCode JSON and Codex TOML settings. It refuses to replace a different abi MCP entry unless --force is supplied. Use --output-json in automation.

Installation locations are platform-native:

Platform	Project skill	Project MCP config	User skill / config
Claude Code	.claude/skills/abi/SKILL.md	.mcp.json	~/.claude/skills/abi, ~/.claude.json
OpenCode	.opencode/skills/abi/SKILL.md	opencode.json	~/.config/opencode/skills/abi, ~/.config/opencode/opencode.json
Codex	.agents/skills/abi/SKILL.md	.codex/config.toml	~/.agents/skills/abi, ~/.codex/config.toml

doctor is read-only and exits non-zero when abi-mcp, the MCP runtime, the skill, or the MCP entry is missing. It initializes the safe server without starting stdio, so a missing mcp extra is detected before the agent launches. Start a new agent session after installing a plugin or when a client does not detect newly added skills automatically.

For Claude Code plugin development:

claude plugin validate integrations/claude-code/abi --strict
claude --plugin-dir integrations/claude-code/abi

For Codex plugin development, validate the distributable bundle with:

python /path/to/plugin-creator/scripts/validate_plugin.py integrations/codex/abi

Direct Codex installation uses .agents/skills/abi for project scope or ~/.agents/skills/abi for user scope, plus the matching .codex/config.toml.

MCP Server

abi-mcp                         # safe: discovery, planning, and result tools
abi-mcp --profile discovery     # read-only discovery and inspection
abi-mcp --profile full          # adds confirmation-gated abi_run

The management profile preserves the complete compatibility surface and is intended for administrative use, not ordinary agent sessions.

Manual MCP configuration uses:

{
  "mcpServers": {
    "abi": {
      "command": "abi-mcp",
      "args": ["--profile", "safe"]
    }
  }
}

Python API (for custom agent code)

import abi

# Compact operating guide for system prompt injection
print(abi.get_agent_guide())

# List all installed analysis plugins
for p in abi.list_plugins_summary():
    print(f"{p['analysis_type']}: {p['name']}")

Run a Biological Analysis Through a Plugin

ABI does not create a separate MCP function for every plugin. The agent calls shared lifecycle tools such as abi_plan and abi_dry_run, then selects the plugin with the analysis_type argument.

1. Translate the biological question into an analysis request

Before selecting a plugin, establish:

• the biological question and expected result;

• input data type and sequencing platform;

• sample IDs, groups, contrasts, or paired-end relationships;

• available reference genomes, annotations, databases, and indexes;

• the intended runtime, compute limits, and output location.

Ask the user when missing information would change the plugin, workflow branch, reference, or biological interpretation. Do not guess a reference genome, sample grouping, or database profile.

2. Discover and select the plugin

Biological goal	analysis_type
Profile a 16S microbial community	amplicon_16s
Compare bulk RNA-seq expression	rnaseq_expression
Analyze a bacterial isolate genome	wgs_bacteria
Quantify metatranscriptomic expression	metatranscriptomics
Profile shotgun metagenomic reads	easymetagenome
Identify and characterize viruses	viral_viwrap
Reconstruct and characterize plasmids	metagenomic_plasmid

Use the installed environment as the source of truth:

abi_list_types({})
abi_export_agent_context({"analysis_type": "rnaseq_expression"})
abi_query({"analysis_type": "rnaseq_expression", "what": "stages"})
abi_query({"analysis_type": "rnaseq_expression", "what": "tools"})

abi_export_agent_context returns the plugin description, standard tables, important artifacts, permissions, error codes, and recovery rules. Use it before constructing a plan.

Its canonical_lifecycle field is the normative phased contract. The safe_sequence field is the same lifecycle flattened to callable ABI tools; the authorization action remains represented by execution_requires_confirmation.

3. Prepare configuration and sample metadata

The Agent lifecycle tools accept paths; they do not invent biological metadata. Use an existing reviewed config and sample sheet, or initialize templates outside MCP with:

abi init --type rnaseq_expression --outdir my-analysis

The user or agent must replace placeholder paths and verify sample metadata. Keep source data read-only and write each attempt to a new result directory.

4. Plan, check, and dry-run

Use the same analysis_type, config, sample sheet, and output assumptions in every call:

abi_plan({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/plan"
})

abi_check({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "engine": "local",
  "check_runtime": true
})

abi_dry_run({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/dry-run"
})

Stop before execution if preflight reports missing inputs, tools, or resources. A successful dry-run proves that planning and command rendering work; it does not prove biological validity.

5. Present an approval summary

Before requesting execution approval, summarize:

• selected plugin and biological purpose;

• samples, platforms, groups, and contrasts;

• planned stages and key tools;

• references, databases, and unresolved warnings;

• runtime backend, output directory, and expected resource demand;

• the exact action that will cross the execution boundary.

Do not invent runtime or storage estimates. Report only estimates supplied by the plan, configuration, scheduler, or user.

6. Execute only after explicit approval

The default MCP safe profile does not expose abi_run. Start the full profile only when execution is needed:

abi-mcp --profile full

First call abi_run with confirm_execution: false to preserve the approval boundary. After the user explicitly approves the summarized plan, repeat the same request with confirm_execution: true.

abi_run({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/run-001",
  "engine": "local",
  "confirm_execution": true
})

Approval applies only to the displayed plugin, inputs, configuration, output path, and runtime. Re-plan and ask again if any of them changes materially.

7. Validate and interpret the result

abi_inspect({"result_dir": "my-analysis/results/run-001"})
abi_validate_result({"result_dir": "my-analysis/results/run-001"})
abi_report({
  "analysis_type": "rnaseq_expression",
  "result_dir": "my-analysis/results/run-001"
})

Read biological values from declared standard tables, not from ad hoc parsing of raw logs. Use provenance for methods and reproducibility, and use plugin reports for limitations and interpretation context.

The Agent should separate three conclusions: execution completed, result contracts passed, and biological acceptance criteria passed. None of these automatically proves the other two.

Safe Sequence

1. abi_list_types — discover installed analysis plugins

2. abi_export_agent_context or abi_doctor_agent — get operating context

3. abi_query — lightweight metadata query (stages, tools, platforms, step I/O)

4. abi_plan — build the execution plan and review its summary

5. abi_check — preflight inputs, resources, executables, and runtime

6. abi_dry_run — write commands, provenance, table skeletons, and report preview

7. abi_inspect or abi_validate_result — verify the dry-run artifacts

8. Present the plugin, inputs, resources, runtime, output path, and warnings

9. abi_run — execute only after explicit user approval

10. abi_inspect, abi_validate_result, and abi_report — validate and interpret results

Transport Methods

CLI JSON (universal)

abi list-types --output-json
abi query --type metatranscriptomics --what stages --output-json
abi plan --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/agent-plan --output-json
abi check --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --no-check-runtime --output-json
abi dry-run --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/agent-dry-run --output-json
abi inspect --result-dir results/agent-dry-run --output-json
abi validate-result --result-dir results/agent-dry-run --allow-empty-tables --output-json
abi report --type metatranscriptomics --result-dir results/agent-dry-run --output-json

All commands return JSON envelopes with status success, confirmation_required, or error.

For abi check, a successful transport envelope may contain result.status: "fail" and a non-zero CLI exit when preflight finds missing inputs or resources. Agents must inspect both status levels.

The bundled example contains placeholder reference paths. Use it for planning and dry-run only; configure real references before biological execution.

Multi-LLM Tools

ABI exports tool descriptors for all major LLM providers from a single source of truth.

# OpenAI-compatible providers (Chat Completions API)
abi export-tools --type metagenomic_plasmid --format openai --provider openai
abi export-tools --type metagenomic_plasmid --format openai --provider deepseek
abi export-tools --type metagenomic_plasmid --format openai --provider zhipu   # 智谱 GLM
abi export-tools --type metagenomic_plasmid --format openai --provider kimi     # Moonshot
abi export-tools --type metagenomic_plasmid --format openai --provider qwen     # 通义千问
abi export-tools --type metagenomic_plasmid --format openai --provider minimax  # MiniMax

# Anthropic Claude (tool_use format)
abi export-tools --type metagenomic_plasmid --format anthropic

# Google Gemini (function_declarations format)
abi export-tools --type metagenomic_plasmid --format gemini

# Include execution tools in export
abi export-tools --type metagenomic_plasmid --format openai --include-execution

OpenAI Tools (legacy, backward compat)

abi export-openai-tools --type metagenomic_plasmid --format responses

MCP

abi-mcp                  # safe profile (default)
abi-mcp --profile full   # includes abi_run

Python

from abi.agent import ABIAgentInterface

# Default: compact error envelopes (no error_type for token efficiency)
agent = ABIAgentInterface()
result = agent.list_types()
plan_json = agent.plan(analysis_type="metatranscriptomics", outdir="results/")

# For debugging: include error_type in error envelopes
agent_debug = ABIAgentInterface(verbose_errors=True)

JSON Envelope Contract

Every ABIAgentInterface method returns a JSON string with one of three statuses:

Status	Meaning	Key fields
success	Operation completed	result holds the payload
confirmation_required	User must approve (run only)	Exit code 2, re-invoke with confirm_execution=true
error	Operation failed	error_code + diagnostic_hints for automated recovery

Error Recovery

On error, inspect in order:

1. error_code and diagnostic_hints in the JSON envelope — each hint carries a structured recovery block (action, api_call, params); act on it directly, and never auto-retry hints whose action is do_not_retry

2. result_dir/provenance/commands.tsv — find failed rows

3. result_dir/provenance/resolved_inputs.tsv — check for missing/placeholder inputs

4. result_dir/provenance/step_logs/<step_id>.stderr.log — raw tool error output

Do not parse raw tool outputs first. Prefer standard tables under tables/.

Contract and Reproducibility Checks

When asked whether a workflow is constrained, verifiable, or reproducible, check the artifacts rather than relying on dry-run alone:

1. execution_plan.json has the expected analysis type, samples, steps, and output paths.

2. provenance/commands.tsv has no failed or unintended skipped steps.

3. provenance/resolved_inputs.tsv has no missing required inputs.

4. provenance/checksums.json exists after real execution with enforced contracts.

5. provenance/tool_versions.tsv and provenance/resources.json identify the executables and resources used.

6. tables/*.tsv contain the biological result rows used by reports.

7. The workflow route and interpretation limits are checked against docs/workflow_validation.md.

Do not claim that a dry-run proves biological validity. Dry-run validates planning and command rendering. Scientific claims require real tool outputs, configured databases, version/resource manifests, and benchmark acceptance checks.

Plan Summarization

abi plan envelopes now include a summary field with pipeline stages, key tools, and platforms. Agents can understand the workflow structure without reading the full execution_plan.json — saving 78-95% tokens on plan output for complex pipelines.

For lightweight metadata queries without plan overhead, use abi query:

# Pipeline-level metadata
abi query --type metagenomic_plasmid --what stages
abi query --type metagenomic_plasmid --what tools
abi query --type metagenomic_plasmid --what platforms

# Step-level I/O detail
abi query --type metagenomic_plasmid --step qc_fastp --what inputs
abi query --type metagenomic_plasmid --step qc_fastp --what outputs

All abi query commands support --output-json for agent consumption.

run vs dispatch

Both execute real tools, but differ in invocation model:

Aspect	run	dispatch
Invocation	CLI command	HTTP endpoint (Job Service)
Blocking	Yes (synchronous)	Returns immediately (async)
Confirmation	--confirm-execution flag	Job queue with confirm_execution in payload
Progress	Inline progress bars / logs	GET /jobs/{id} polling
Cancel	Ctrl+C (SIGINT, best-effort)	POST /jobs/{id}/cancel (SIGTERM → SIGKILL)
Use case	Interactive agent calls	Long-running batch jobs, remote execution

Prefer run for interactive sessions. Use dispatch when execution time exceeds agent timeout or when running on remote machines via Job Service.

Troubleshooting Common Failures

Tool not found (TOOL_NOT_FOUND)

The tool executable is not on PATH. Check:

# Verify conda environment is activated
conda activate <env_name>

# Or list which tools are available
abi check-resources --type <analysis_type>

Missing resource (MISSING_RESOURCE)

A required database or reference file is missing:

# See what's missing
abi check-resources --type <analysis_type>

# Install missing resources
abi setup-resources --type <analysis_type> --confirm

Contract violation (CONTRACT_VIOLATION)

A tool’s output didn’t match the expected contract:

1. Check provenance/step_logs/<step_id>.stderr.log for tool errors

2. Verify input files exist and are not empty

3. Check if the tool version changed — output formats may differ

4. If the contract is too strict, adjust min_size or assertions in the tool contract

Dry-run succeeds but real execution fails

1. Verify conda environments are installed: ls envs/

2. Check if required databases are downloaded: abi check-resources --type <analysis_type>

3. Ensure input FASTQ files exist and are readable

4. Check disk space and memory: some tools need 16GB+ RAM

Permission denied

ABI enforces a 3-tier permission model:

• read_only operations (list_types, query, inspect) — always allowed

• planning_write operations (plan, dry_run, report) — write plans/provenance only

• execution (run) — requires confirm_execution=true

If run returns confirmation_required, re-invoke with --confirm-execution.

Parallel execution not speeding up

Check config.execution.parallel and config.execution.workers in your config:

execution:
  parallel: true
  workers: 8

Parallel execution is sample-level. Single-sample pipelines with few steps won’t benefit. Multi-sample pipelines will see near-linear speedup up to worker count.

Golden Traces

Known-good agent call sequences are stored in golden_traces/ and replayed by tests/integration/test_golden_traces.py.