BioDSA Agent Execution Skill

Core Principle

Write the script AND run it. When a user asks to execute a BioDSA agent, do NOT just hand them a script and tell them to run it themselves. You must:

1. •Write the execution script
2. •Run the script via the terminal to start the agent
3. •Monitor the output and report the results back to the user
4. •Collect and present the deliverables (JSON, PDF, artifacts)

This is the key difference from the dev skill — the exec skill is about completing the task end-to-end, not just scaffolding code.

When to Use This Skill

Use this skill when the user wants to:

• •Run an existing BioDSA agent on a task (not build a new one)
• •Execute a biomedical task using an agent and get results
• •Pick the right agent for a given biomedical task
• •Run agents in batch over datasets or benchmark files
• •Chain agent runs (feed one agent's output into another)

Do NOT use this skill for creating new agents — use the biodsa-agent-dev-skills for that.

Agent Catalog

These agents are available in BioDSA. Read 01-agent-catalog.md for full details on each.

Model Selection — Use Frontier Models

IMPORTANT: BioDSA agents perform complex multi-step biomedical reasoning. Always use frontier-tier models to ensure high-quality results. Weaker models (gpt-4o, gpt-4o-mini, claude-sonnet, etc.) produce significantly worse results and should be avoided unless the user explicitly requests them.

When reading the user's .env file, check the MODEL_NAME value. If it is set to a weaker model, warn the user that it may produce poor results and suggest upgrading.

Quick-Start: Running an Agent

When a user describes a task, follow these steps in order:

Step 0: Ensure Environment is Ready

Before anything, verify the BioDSA environment is set up. Read 00-environment-setup.md and run the checks. If the environment is not ready (no conda/pipenv env, missing dependencies, no .env), set it up automatically — do not ask the user to do it manually. This includes:

• •Creating an isolated conda/pipenv environment (never install into the user's base Python)
• •Running pipenv install to install all dependencies
• •Configuring .env with API keys
• •Optionally building the Docker sandbox

Step 1: Check Model Configuration

Verify the .env file has MODEL_NAME set to a frontier model (see Model Selection above). If it is set to a weaker model like gpt-4o or gpt-4o-mini, warn the user and suggest upgrading to gpt-5 / claude-opus-4-20250514 / gemini-2.5-pro.

Step 2: Pick the Agent

Match the user's task to the right agent from the catalog above. See 01-agent-catalog.md for the full decision guide and go() signatures.

Step 3: Write the Script

Generate a complete Python script at the repo root (e.g., run_task.py). Follow the patterns in 02-execution-patterns.md. Use the template below.

Step 4: Run the Script

IMPORTANT: Do NOT stop after writing the script. Execute it immediately:

cd /path/to/BioDSA
python run_task.py

Monitor the output. Agent runs can take seconds to minutes depending on complexity. Wait for the script to complete.

Step 5: Report Results

After the script finishes:

• •Show the user the final_response from the terminal output
• •Tell the user where deliverables were saved (JSON, PDF, artifacts)
• •If the run failed, diagnose the error and fix the script, then re-run
• •If the run succeeded, summarize the key findings for the user

Execution Template

Every agent script follows this skeleton:

import sys, os
REPO_BASE_DIR = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, REPO_BASE_DIR)

from dotenv import load_dotenv
load_dotenv(os.path.join(REPO_BASE_DIR, ".env"))

from biodsa.agents import <AgentClass>

agent = <AgentClass>(
    model_name=os.environ.get("MODEL_NAME", "gpt-5"),
    api_type=os.environ.get("API_TYPE", "azure"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
)

# (Optional) Register data for analysis agents
# agent.register_workspace("/path/to/data")

results = agent.go("<user's task description>")

# Save deliverables
os.makedirs("output", exist_ok=True)
print(results.final_response)
results.to_json(output_path="output/results.json")
results.to_pdf(output_dir="output")

What "Done" Looks Like

You are NOT done until:

• •The script has been written to a file
• •The script has been executed in the terminal
• •The agent has finished running and produced output
• •You have reported the results (or the error) back to the user

Skill Library Contents

Key Paths