​
Adding Tools and Agents

You can extend BioCortex with new tools (agent skills) and optional external agents (e.g. AI-Researcher) in a uniform way. The same tools appear in the Planner/Executor and on the Resources page.

​
Two Ways to Extend

TypeWhat it isHow to add
Tools (DomainTools)Callable skills: one name, one function, clear parameters. The Planner/Executor choose which tool to use and generate code that calls it.Implement a module with get_*_tools() returning list[DomainTool], register in biocortex.domains.loader.
External agentsAnother system (e.g. AI-Researcher) that runs a long pipeline (literature → idea → implementation).Expose it as one or a few tools that invoke that system (subprocess, HTTP, or in-process).
More agent skills = more DomainTools. Each tool is a single skill (e.g. search_pubmed, autofigure_generate, ai_researcher_run). External agents are wrapped as one or several such tools.

​
Adding a New Tool Module

Same pattern as Browser and AutoFigure:

​
1. Create a tool module

Under biocortex/tools/, e.g. biocortex/tools/my_tool.py.

​
2. Implement wrapper functions

def my_skill(arg1: str, arg2: int = 10) -> dict:
    # ... do work ...
    return {"success": True, "result": "..."}

​
3. Define DomainTools and a getter

from biocortex.domains.base import DomainTool, ToolParameter, ParamType

def get_my_tools() -> list[DomainTool]:
    return [
        DomainTool(
            name="my_skill",
            description="What this skill does (used by retrieval and Planner).",
            domain="literature",  # or genomics, protocols, etc.
            required_parameters=[
                ToolParameter("arg1", ParamType.STRING, "Description", required=True),
            ],
            optional_parameters=[
                ToolParameter("arg2", ParamType.INTEGER, "Optional", required=False, default=10),
            ],
            function=my_skill,
            language="python",
            module_path="biocortex.tools.my_tool",
        ),
    ]

​
4. Register in the loader

In biocortex/domains/loader.py: 
try:
    from biocortex.tools.my_tool import get_my_tools
    registry.register_many(get_my_tools())
    count += len(get_my_tools())
except ImportError:
    pass

​
5. Optional dependency

In requirements.txt: 
# my_tool optional
# some-package>=1.0
After that, the hybrid retriever and Planner see my_skill and can generate code that calls it when the task matches.

​
Web UI

The same tools are used when you run an analysis from the Web UI. The backend loads all registered tools, the retriever picks relevant ones, the Planner builds the plan (Plan panel), and the Executor runs code that calls these tools. No extra setup — if a tool is in the registry, it can appear in the plan and on the Resources page.

​
Adding AI-Researcher (or Similar External Agents)

AI-Researcher is a full autonomous research pipeline: literature → idea → implementation → (optional) paper. It uses its own env and is invoked via subprocess or CLI. You can add it to BioCortex as one or two tools that invoke that pipeline. Then a task like “Given these papers, generate a research idea and implementation” can delegate to AI-Researcher.
  • Add biocortex/tools/ai_researcher_tool.py with tools such as:
    • ai_researcher_run_reference_based — run with a list of reference papers (idea generated by AI-Researcher).
    • ai_researcher_run_detailed_idea — run with a detailed idea + optional references.
  • Each tool runs AI-Researcher via subprocess (or HTTP if you expose an API) and returns job id, output paths, or summary.
  • Register in loader.py behind try/except; document env vars (e.g. AI_RESEARCHER_PATH, OPENROUTER_API_KEY).
  • Do not add AI-Researcher to requirements.txt by default (heavy). Document: “Optional: install AI-Researcher and set AI_RESEARCHER_PATH”.

​
Option B: Run AI-Researcher separately

  • Use AI-Researcher’s own UI/CLI for the full pipeline.
  • Use BioCortex for other tasks (single-cell, AutoFigure, browser tools). No code change.

​
Caveats

  • Long-running: Bridge should return quickly with job id or path; increase Executor timeout for that step if needed.
  • Env: AI-Researcher expects its own env (e.g. OPENROUTER_API_KEY, COMPLETION_MODEL, CATEGORY). You can reuse BioCortex’s .env and set the rest in the bridge or a dedicated .env.
  • Docker: Bridge can call docker run ... or a script that starts the container.

​
Summary

  • More skills → Add more DomainTool entries and register in loader.py. No limit.
  • External agents → Wrap as one or more tools; keep optional in loader and requirements.
  • AI-Researcher is integrated as optional bridge tools; set AI_RESEARCHER_PATH and its .env. If not set, tools return a clear error when called.
See AutoFigure & AI-Researcher for details on the built-in optional integrations.