🧬 BioLink Agent

English | 繁體中文

A multi-agent AI platform for biomedical and genomic research. BioLink Agent translates natural language questions into structured queries across multiple scientific databases, gathers evidence, and synthesizes cited answers.

✨ Features

• Multi-Agent Architecture: A CoordinatorAgent routes tasks to domain-specialized agents (Literature, Variant, Genomics, Pathway, Protein, Disease, dbSNP, and more).
• Pluggable Scientific Tools: Supports PubMed, NCBI ClinVar, dbSNP, Ensembl, UniProt, and 10+ extensible tool interfaces.
• Universal LLM Adapter: Works with Google Gemini, OpenAI, and Anthropic Claude.
• Async Database Logging: SQLite-based evidence tracking via SQLAlchemy + aiosqlite.
• REST API: FastAPI backend with OpenAPI docs at /docs.

🏗️ Architecture

biolink-agent/
├── agents/          # CoordinatorAgent + domain-specific agents
├── api/             # FastAPI routes
├── core/            # LLM adapter, config
├── database/        # SQLAlchemy models, async DB
├── tools/           # Scientific tool interfaces (PubMed, ClinVar, ...)
├── main.py          # Application entrypoint
└── tests/           # Test suite

🚀 Quick Start

Prerequisites

• Python 3.10+

Installation

git clone https://github.com/jhjhong/biolink-agent.git
cd biolink-agent

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env and fill in your API keys

Running the API Server

source venv/bin/activate
python main.py

The API will be available at http://localhost:8000

• Interactive docs: http://localhost:8000/api/docs
• OpenAPI schema: http://localhost:8000/api/openapi.json

📡 API Reference

POST /api/query

Submit a natural language biomedical question.

Request body:

Field	Type	Description
query	string	Natural language question (English or Traditional Chinese)

Response:

Field	Type	Description
answer	string	Synthesized answer with evidence
plan	array	Agent execution plan (which agents were invoked)
evidence_collected	integer	Number of evidence pieces gathered

---

💡 Usage Examples

Via curl

# Look up a gene across multiple databases
curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the pathogenic variants in BRCA1 and their clinical significance?"}'

# Query by rsID
curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Tell me about rs7412 in dbSNP"}'

# Traditional Chinese query
curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "EGFR 基因有哪些已知的藥物靶點？"}'

Via Python

import httpx

response = httpx.post(
    "http://localhost:8000/api/query",
    json={"query": "What is the allele frequency of rs7412 in global populations?"}
)
result = response.json()
print(result["answer"])

Example Natural Language Queries

Query Type	Example
Gene overview	What are the genomic coordinates of TP53 in Ensembl and its protein length in UniProt?
Variant lookup	rs7412 — variant type, gene, and allele frequency
VCF coordinate	What variant is at chr8:19962213 C>T in dbSNP?
Clinical variants	What pathogenic BRCA1 variants are in ClinVar?
Drug targets	What drugs target EGFR? Check GWAS and DGIdb
Protein structure	Fetch the AlphaFold structure for TP53 and summarize its domains
Pathway	Which Reactome pathways involve KRAS?
Expression	In which tissues is BRCA2 most highly expressed? (Human Protein Atlas)
Literature	Recent PubMed papers on CRISPR treatment of sickle cell disease
繁體中文	查詢 BRCA1 在不同組織的表現量，以及與它有交互作用的蛋白質

Agent Routing

The CoordinatorAgent automatically selects the right agent(s) for each query:

Agent	Databases	Triggered by
LiteratureAgent	PubMed	Paper/publication queries
VariantAgent	ClinVar	Pathogenicity, ACMG classification
DbSNPAgent	dbSNP	rsIDs, SNP/indel lookups, VCF coords
GenomicsAgent	Ensembl	Gene coordinates, transcripts
ProteinAgent	UniProt, AlphaFold	Protein sequence, structure
StructureAgent	RCSB PDB	3D structure, PDB entries
PathwayAgent	Reactome	Biological pathways
ExpressionAgent	Human Protein Atlas	Tissue expression
InteractionAgent	STRING DB	Protein-protein interactions
OntologyAgent	QuickGO	Gene Ontology terms
ChemAgent	PubChem, ChEMBL	Chemical compounds, drugs
PharmacogenomicsAgent	DGIdb	Drug-gene interactions
DiseaseAgent	GWAS Catalog	Disease associations
TaxonomyAgent	NCBI Taxonomy	Species classification

🤖 MCP Integration

BioLink-Agent supports the Model Context Protocol (MCP), allowing you to mount it as a tool in MCP-compatible clients like Claude Desktop or Cursor. This exposes a single ask_biolink tool that handles task planning, sub-agent routing, and evidence gathering.

Running the MCP Server

# Ensure dependencies are installed
pip install -r requirements.txt

# You can run it directly (stdio transport)
python mcp_server.py

Claude Desktop Configuration

Add the following to your claude_desktop_config.json (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "biolink": {
      "command": "python",
      "args": ["/absolute/path/to/biolink-agent/mcp_server.py"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "OPENAI_API_KEY": "optional_api_key"
      }
    }
  }
}

Restart Claude Desktop, and you can now ask it biomedical questions directly. Claude will use the ask_biolink tool to fetch real-world data and synthesize answers!

⚙️ Configuration

Copy .env.example to .env and configure your API keys:

Variable	Description
GEMINI_API_KEY	Google Gemini API key (Fallback if not provided via Web UI)
OPENAI_API_KEY	OpenAI API key (Fallback if not provided via Web UI)
ANTHROPIC_API_KEY	Anthropic Claude API key (Fallback if not provided via Web UI)
NCBI_API_KEY	(Optional) Raises NCBI/dbSNP API rate limit from 3 to 10 reqs/sec
OPENALEX_EMAIL	(Optional) Join OpenAlex polite pool for faster literature searches

🌐 Web UI & CORS Deployment

If you are deploying the BioLink Web Frontend (e.g., on Vercel) alongside this backend, you MUST configure the CORS origin so the backend accepts requests from your frontend.

To do this, add FRONTEND_URL to your backend's .env file (this is not in the example file to keep it clean):

# For local development:
FRONTEND_URL=http://localhost:3000

# For production deployment:
FRONTEND_URL=https://your-vercel-app-url.vercel.app

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

📄 License

Apache 2.0 License — see LICENSE for details.