Empower your materials science research with AtomGPT's Agentic AI API (AGAPI). AGAPI removes complex software setups, commercial API cost allowing you to perform advanced predictions, analyses, and explorations through natural language or Python, accelerating materials discovery and design. AGAPI implements a modular architecture separating the reasoning layer (LLM brain) from the execution layer (scientific tools and databases as hands) through a unified REST API interface. This design follows established principles of agentic AI systems.
1. Get your API key — sign up at AtomGPT.org → Account → Settings, then:
pip install agapi jarvis-tools scipy httpx
export AGAPI_KEY="sk-your-key-here"2. Initialize client and agent:
importosfromagapi.agents.clientimportAGAPIClientfromagapi.agentsimportAGAPIAgentfromagapi.agents.functionsimport*fromjarvis.io.vasp.inputsimportPoscar# Direct function calls (API client)client=AGAPIClient(api_key=os.environ.get("AGAPI_KEY"))
result=query_by_formula("Si", client)
print(result["materials"][25]["formula"], result["materials"][25]["mbj_bandgap"])
# Natural language queries (AI agent)agent=AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
response=agent.query_sync("What is the bandgap of Silicon?")
print(response)SI_PRIM="""Si1.00 2.734 2.7342.734 0 2.7342.734 2.734 0Si2direct0 0 00.25 0.25 0.25"""GAAS_PRIM="""GaAs1.00 2.875 2.8752.875 0 2.8752.875 2.875 0Ga As1 1direct0 0 00.25 0.25 0.25"""SI_XRD="""28.44 1.0047.30 0.5556.12 0.30"""Access JARVIS-DFT and more.
API Example:
fromagapi.agents.functionsimport (
query_by_formula,
query_by_jid,
query_by_elements,
query_by_property,
find_extreme,
alignn_predict,
alignn_ff_relax,
slakonet_bandstructure,
generate_interface,
make_supercell,
substitute_atom,
create_vacancy,
generate_xrd_pattern,
protein_fold,
diffractgpt_predict,
alignn_ff_single_point,
alignn_ff_optimize,
alignn_ff_md,
pxrd_match,
xrd_analyze,
microscopygpt_analyze,
query_mp,
query_oqmd,
search_arxiv,
search_crossref,
openfold_predict,
list_jarvis_columns,
)
r=query_by_formula("Si", client)
assert"error"notinrr=query_by_jid("JVASP-1002", client)
assertisinstance(r.get("POSCAR"), str)
r=query_by_elements("Si", client)
assert"error"notinrr=query_by_property("bandgap", 0.1, 3.0, elements="Si", api_client=client)
assert"error"notinrr=find_extreme("bulk modulus", True, elements="Si", api_client=client)
assert"error"notinrNatural Language Example:
agent.query_sync("Show me all MgB2 polymorphs")
agent.query_sync("What's the Tc_Supercon for MgB2 and what's the JARVIS-ID for it?")
agent.query_sync("What's the stiffest Si,O material?")
agent.query_sync("Find materials with bulk modulus > 200 GPa")
agent.query_sync("Compare bandgaps across BN, AlN, GaN, InN")
agent.query_sync("What are the formation energies of SiC, AlN, MgO?")Predict bandgap, formation energy, elastic moduli, and more using graph neural networks.
API Example:
fromagapi.agents.functionsimportalignn_predictr=alignn_predict(jid="JVASP-1002", api_client=client)
assertr.get("status") =="success"Natural Language Example:
agent.query_sync("Predict properties of JARVIS-ID JVASP-1002 with ALIGNN")
agent.query_sync(f"Predict properties using ALIGNN for this structure:\n\n{SI_PRIM}")Structure relaxation, single-point energy, and MD with near-DFT accuracy.
API Example:
fromagapi.agents.functionsimportalignn_ff_relax, alignn_ff_single_pointr=alignn_ff_relax(SI_PRIM, api_client=client)
assertr.get("status") =="success"print(Poscar.from_string(r["relaxed_poscar"])) # view relaxed structurer=alignn_ff_single_point(SI_PRIM, api_client=client)
assert"energy_eV"inrNatural Language Example:
agent.query_sync(f"Optimize structure with ALIGNN-FF:\n\n{SI_PRIM}")
agent.query_sync("Get the single-point energy of this Si primitive cell.")Tight-binding band structures from neural network Slater-Koster parameters.
API Example:
fromagapi.agents.functionsimportslakonet_bandstructurer=slakonet_bandstructure(SI_PRIM, api_client=client)
assertr.get("status") =="success"Natural Language Example:
agent.query_sync("Compute the band structure of Si.")
agent.query_sync(f"Plot the electronic band structure for this POSCAR:\n\n{SI_PRIM}")Match PXRD patterns, identify phases, and analyze experimental diffraction data.
API Example:
fromagapi.agents.functionsimportpxrd_match, xrd_analyze, diffractgpt_predictr=pxrd_match("Si", SI_XRD, api_client=client)
assertisinstance(r, dict)
if"matched_poscar"inr:
print(Poscar.from_string(r["matched_poscar"])) # view matched structurer=xrd_analyze("Si", SI_XRD, api_client=client)
assertisinstance(r, dict)
r=diffractgpt_predict("Si", "28.4(1.0),47.3(0.49)", client)
assertisinstance(r, dict)Natural Language Example:
agent.query_sync("Identify the phase from this XRD pattern for Silicon: [XRD data]")
agent.query_sync("Analyze this PXRD pattern and suggest possible structures.")Analyze STEM, TEM, and electron microscopy images using AI — identify atomic columns, measure lattice spacings, detect defects, and interpret microstructure.
API Example:
fromagapi.agents.functionsimportmicroscopygpt_analyzer=microscopygpt_analyze("HRTEM image of Si lattice", api_client=client)
assertisinstance(r, dict)Natural Language Example:
agent.query_sync("Analyze this STEM image of a GaN thin film: [image]")
agent.query_sync("What defects are visible in this HRTEM image?")
agent.query_sync("Measure the d-spacing from this electron diffraction pattern.")Supercells, substitutions, vacancies, and XRD pattern generation — runs locally, no API call needed.
API Example:
fromagapi.agents.functionsimportmake_supercell, substitute_atom, create_vacancy, generate_xrd_patternr=make_supercell(SI_PRIM, [2, 2, 1])
assertr["supercell_atoms"] >r["original_atoms"]
print(f"Original atoms: {r['original_atoms']}, Supercell atoms: {r['supercell_atoms']}")
# Expected: Original atoms: 2, Supercell atoms: 8r=substitute_atom(GAAS_PRIM, "Ga", "Al", 1)
assert"Al"inr["new_formula"]
# Expected new_formula: AlAsr=create_vacancy(GAAS_PRIM, "Ga", 1)
assertr["new_atoms"] ==r["original_atoms"] -1# Expected: one fewer atom than originalr=generate_xrd_pattern(SI_PRIM)
assertr["formula"] =="Si"Natural Language Example:
agent.query_sync("Make a 2x1x1 supercell of the most stable GaN.")
agent.query_sync("Substitute one Ga with Al in this GaAs structure.")
agent.query_sync("Create a Ga vacancy in GaAs and predict its properties.")Build heterostructure interfaces between two materials.
API Example:
fromagapi.agents.functionsimportgenerate_interfacer=generate_interface(SI_PRIM, GAAS_PRIM, api_client=client)
assertr.get("status") =="success"Natural Language Example:
agent.query_sync(""" Create a GaN/AlN heterostructure interface: 1. Find GaN (most stable) 2. Find AlN (most stable) 3. Generate (001)/(001) interface 4. Show POSCAR""", max_context_messages=20)Search arXiv and Crossref for relevant research papers.
API Example:
fromagapi.agents.functionsimportsearch_arxiv, search_crossrefr=search_arxiv("GaN", max_results=2, api_client=client)
assertisinstance(r, dict)
r=search_crossref("GaN", rows=2, api_client=client)
assertisinstance(r, dict)Natural Language Example:
agent.query_sync("Find recent papers on perovskite solar cells on arXiv.")
agent.query_sync("Search for publications about ALIGNN neural networks.")agent.query_sync("""1. Find all GaN materials in the JARVIS-DFT database2. Get the POSCAR for the most stable one3. Make a 2x1x1 supercell4. Substitute one Ga with Al5. Generate powder XRD pattern6. Optimize structure with ALIGNN-FF7. Predict properties with ALIGNN""", max_context_messages=20, verbose=True)
agent.query_sync("""Create a GaN/AlN heterostructure interface:1. Find GaN (most stable)2. Find AlN (most stable)3. Generate (001)/(001) interface4. Show POSCAR""", max_context_messages=20, verbose=True)AGAPI supports multiple LLM backends. Set model when initializing the agent:
agent=AGAPIAgent(
api_key=os.environ.get("AGAPI_KEY"),
model="openai/gpt-oss-20b" )Available models:
| Provider | Model |
|---|---|
| OpenAI | openai/gpt-oss-20b |
| OpenAI | openai/gpt-oss-120b |
| Meta | meta/llama-4-maverick-17b-128e-instruct |
| Meta | meta/llama-3.2-90b-vision-instruct |
| Meta | meta/llama-3.2-1b-instruct |
google/gemini-2.5-flash | |
google/gemma-3-27b-it | |
| DeepSeek | deepseek-ai/deepseek-v3.1 |
| Moonshot | moonshotai/kimi-k2-instruct-0905 |
| Qwen | qwen/qwen3-next-80b-a3b-instruct |
| Function | Description |
|---|---|
query_by_formula | Search by chemical formula |
query_by_jid | Fetch by JARVIS ID |
query_by_elements | Filter by constituent elements |
query_by_property | Filter by property range |
find_extreme | Find max/min property material |
alignn_predict | GNN property prediction |
alignn_ff_relax | Structure relaxation |
alignn_ff_single_point | Single-point energy |
slakonet_bandstructure | TB band structure |
generate_interface | Heterostructure builder |
make_supercell | Supercell generation |
substitute_atom | Atomic substitution |
create_vacancy | Vacancy creation |
generate_xrd_pattern | Simulated XRD |
pxrd_match / xrd_analyze | XRD phase matching |
diffractgpt_predict | AI XRD interpretation |
microscopygpt_analyze | AI STEM/TEM image analysis |
query_mp | Materials Project query |
search_arxiv / search_crossref | Literature search |
protein_fold | Protein structure prediction |
If you find this work helpful, please cite:
AGAPI-Agents: An Open-Access Agentic AI Platform for Accelerated Materials Design on AtomGPT.orghttps://doi.org/10.48550/arXiv.2512.11935
ChatGPT Material Explorer: Design and Implementation of a Custom GPT Assistant for Materials Science Applicationshttps://doi.org/10.1016/j.commatsci.2025.114063
The JARVIS Infrastructure Is All You Need for Materials Designhttps://doi.org/10.1016/j.commatsci.2025.114063
📄 Full publication list: Google Scholar
- 🔬 Research Group: AtomGPTLab @ JHU
- 📖 Docs: AtomGPT.org/docs
- 🧪 Colab: AGAPI Example Notebook
▶️ YouTube: Demo Playlist
AGAPI (ἀγάπη) is a Greek word meaning unconditional love.
AtomGPT.org can make mistakes — please verify critical results. We hope this API fosters open, collaborative, and accelerated discovery in materials science.