agapi

🌐 AtomGPT.org API (AGAPI): Agentic AI for Materials Science

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.

🚀 Quickstart

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:

import os
from agapi.agents.client import AGAPIClient
from agapi.agents import AGAPIAgent
from agapi.agents.functions import *
from jarvis.io.vasp.inputs import Poscar

# 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)

---

✨ Key Capabilities

Common Inputs

SI_PRIM = """Si
1.0
0 2.734 2.734
2.734 0 2.734
2.734 2.734 0
Si
2
direct
0 0 0
0.25 0.25 0.25
"""

GAAS_PRIM = """GaAs
1.0
0 2.875 2.875
2.875 0 2.875
2.875 2.875 0
Ga As
1 1
direct
0 0 0
0.25 0.25 0.25
"""

SI_XRD = """28.44 1.00
47.30 0.55
56.12 0.30
"""

---

1. Materials API Query

Access JARVIS-DFT and more.

API Example:

from agapi.agents.functions import (
    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" not in r

r = query_by_jid("JVASP-1002", client)
assert isinstance(r.get("POSCAR"), str)

r = query_by_elements("Si", client)
assert "error" not in r

r = query_by_property("bandgap", 0.1, 3.0, elements="Si", api_client=client)
assert "error" not in r

r = find_extreme("bulk modulus", True, elements="Si", api_client=client)
assert "error" not in r

Natural 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?")

---

2. AI Property Prediction (ALIGNN)

Predict bandgap, formation energy, elastic moduli, and more using graph neural networks.

API Example:

from agapi.agents.functions import alignn_predict

r = alignn_predict(jid="JVASP-1002", api_client=client)
assert r.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}")

---

3. AI Force Field (ALIGNN-FF)

Structure relaxation, single-point energy, and MD with near-DFT accuracy.

API Example:

from agapi.agents.functions import alignn_ff_relax, alignn_ff_single_point

r = alignn_ff_relax(SI_PRIM, api_client=client)
assert r.get("status") == "success"
print(Poscar.from_string(r["relaxed_poscar"]))   # view relaxed structure

r = alignn_ff_single_point(SI_PRIM, api_client=client)
assert "energy_eV" in r

Natural 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.")

---

4. Band Structure (SlakoNet)

Tight-binding band structures from neural network Slater-Koster parameters.

API Example:

from agapi.agents.functions import slakonet_bandstructure

r = slakonet_bandstructure(SI_PRIM, api_client=client)
assert r.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}")

---

5. XRD / DiffractGPT

Match PXRD patterns, identify phases, and analyze experimental diffraction data.

API Example:

from agapi.agents.functions import pxrd_match, xrd_analyze, diffractgpt_predict

r = pxrd_match("Si", SI_XRD, api_client=client)
assert isinstance(r, dict)
if "matched_poscar" in r:
    print(Poscar.from_string(r["matched_poscar"]))   # view matched structure

r = xrd_analyze("Si", SI_XRD, api_client=client)
assert isinstance(r, dict)

r = diffractgpt_predict("Si", "28.4(1.0),47.3(0.49)", client)
assert isinstance(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.")

---

6. STEM / MicroscopyGPT

Analyze STEM, TEM, and electron microscopy images using AI — identify atomic columns, measure lattice spacings, detect defects, and interpret microstructure.

API Example:

from agapi.agents.functions import microscopygpt_analyze

r = microscopygpt_analyze("HRTEM image of Si lattice", api_client=client)
assert isinstance(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.")

---

7. Structure Manipulation

Supercells, substitutions, vacancies, and XRD pattern generation — runs locally, no API call needed.

API Example:

from agapi.agents.functions import make_supercell, substitute_atom, create_vacancy, generate_xrd_pattern

r = make_supercell(SI_PRIM, [2, 2, 1])
assert r["supercell_atoms"] > r["original_atoms"]
print(f"Original atoms: {r['original_atoms']}, Supercell atoms: {r['supercell_atoms']}")
# Expected: Original atoms: 2, Supercell atoms: 8

r = substitute_atom(GAAS_PRIM, "Ga", "Al", 1)
assert "Al" in r["new_formula"]
# Expected new_formula: AlAs

r = create_vacancy(GAAS_PRIM, "Ga", 1)
assert r["new_atoms"] == r["original_atoms"] - 1
# Expected: one fewer atom than original

r = generate_xrd_pattern(SI_PRIM)
assert r["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.")

---

8. Interface Generation

Build heterostructure interfaces between two materials.

API Example:

from agapi.agents.functions import generate_interface

r = generate_interface(SI_PRIM, GAAS_PRIM, api_client=client)
assert r.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)

---

9. Literature Search

Search arXiv and Crossref for relevant research papers.

API Example:

from agapi.agents.functions import search_arxiv, search_crossref

r = search_arxiv("GaN", max_results=2, api_client=client)
assert isinstance(r, dict)

r = search_crossref("GaN", rows=2, api_client=client)
assert isinstance(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.")

---

🔧 Multi-Step Agentic Workflow

agent.query_sync("""
1. Find all GaN materials in the JARVIS-DFT database
2. Get the POSCAR for the most stable one
3. Make a 2x1x1 supercell
4. Substitute one Ga with Al
5. Generate powder XRD pattern
6. Optimize structure with ALIGNN-FF
7. 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) interface
4. Show POSCAR
""", max_context_messages=20, verbose=True)

---

🤖 Supported LLM Backends

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:

---

📦 Available APIs/Functions

...

📖 References

If you find this work helpful, please cite:

1. AGAPI-Agents: An Open-Access Agentic AI Platform for Accelerated Materials Design on AtomGPT.org https://doi.org/10.48550/arXiv.2512.11935

2. ChatGPT Material Explorer: Design and Implementation of a Custom GPT Assistant for Materials Science Applications https://doi.org/10.1016/j.commatsci.2025.114063

3. The JARVIS Infrastructure Is All You Need for Materials Design https://doi.org/10.1016/j.commatsci.2025.114063

📄 Full publication list: Google Scholar

---

📚 Resources

• 🔬 Research Group: AtomGPTLab @ JHU
• 📖 Docs: AtomGPT.org/docs
• 🧪 Colab: AGAPI Example Notebook
• ▶️ YouTube: Demo Playlist

---

❤️ Note

AGAPI (ἀγάπη) is a Greek word meaning unconditional love.

Disclaimer

AtomGPT.org can make mistakes — please verify critical results. We hope this API fosters open, collaborative, and accelerated discovery in materials science.