AGAPI-Agents Codebase Overview

• AGAPI-Agents Codebase is an open-access agentic AI platform that integrates multiple LLMs and materials-science tools to drive reproducible and scalable research.
• The platform utilizes a four-stage pipeline—Agent, Planner, Executor, and Summarizer—to decompose and execute complex, multi-step research workflows efficiently.
• Its modular structure supports diverse functionalities including RESTful API endpoints, local Python toolchains, and integration with open-source LLM backends, enhancing materials design and property prediction.

AGAPI-Agents is an open-access agentic AI platform developed to accelerate and unify computational materials research by integrating multiple open-source LLMs with a broad suite of materials-science tools and databases within a transparent, reproducible orchestration framework. The codebase is publicly available at https://github.com/atomgptlab/agapi and underpins the AtomGPT.org ecosystem, supporting complex, multi-step research workflows in materials design, property prediction, and inverse engineering using both RESTful APIs and local Python toolchains (2512.11935).

1. System Architecture and Pipeline

AGAPI-Agents implements a four-stage Agent–Planner–Executor–Summarizer pipeline, each encapsulating a distinct function in the autonomous workflow execution process:

• Agent (Reasoning Layer): Functions as the platform’s LLM-powered “brain.” Receives user queries, context, and available tool metadata, outputting a structured execution plan—expressed as a JSON schema—either for single-step execution or further decomposition.
• Planner: Receives the Agent’s plan and decomposes it into ordered, dependency-resolved subtasks, outputting an explicit workflow graph or stepwise sequence to the Executor. The Planner leverages tool IO schemas to ensure task compatibility.
• Executor: Calls both external (REST) and internal (Python-wrapped) endpoint tools, managing asynchronous execution, rate-limiting, and automatic retries. Intermediate results are captured for context-sensitive decision making and are passed forward or looped back for conditional planning.
• Summarizer: Validates and collates the results from all execution steps, synthesizes human-readable summaries, and formats output as text, tables, data visualizations, or structure files.

The agentic pipeline is designed for both direct (single-step) and recursive (multi-step) tasks, supporting advanced research use cases such as defect engineering, heterostructure assembly, and powder XRD analysis (2512.11935).

2. Codebase Structure and Key Components

The repository adopts a modular directory hierarchy to facilitate code clarity, extensibility, and specialization for diverse materials science domains:

Directory	Representative Files	Functionality/Domain
agents/	base_agent.py, defect_agent.py	Core logic, domain-specific workflows
planner/	planner.py	Workflow decomposition, dependency graph
executor/	http_executor.py, local_tool_executor.py	REST/Local tool integration, job handling
summarizer/	summarizer.py	Output aggregation, formatting
tools/	tool_registry.py, jarvis_tool.py	Tool definition, registration, schema
workflows/	workflow_defs.py	Predefined workflows (Python/YAML/DSL)
LLM/	llm_adapter.py, ollama_adapter.py	LLM backend abstraction and adapters
Root-level	api_client.py, settings.py	Python client, configuration

Key classes and interfaces include:

• AgentManager: Orchestrates workflow instantiation and execution.
• Planner.plan(query): Converts input into a Workflow object.
• Executor.run_step(step): Executes a specified workflow action.
• Summarizer.summarize(context): Synthesizes results for end-user presentation.
• ToolRegistry: Dynamic registration and lookup of tools and schemas.

The structure provides domain-specific agents, e.g., defect_agent.py for defect engineering, and standardizes interaction with both internal tools and external APIs (2512.11935).

3. LLM Integration and Backend Support

AGAPI-Agents interfaces with an array of open-source LLM backends, supporting model selection and runtime adaptation via the LLMAdapter abstract interface. Supported models include:

• Llama-3.2-90B-Vision
• DeepSeek-V3
• Qwen3-Next-80B
• Gemma-3-27B
• Kimi-K2
• GPT-OSS-20B (default)
• GPT-OSS-120B
• Phi-4

All LLMs implement standardized generate and function_call methods. Backend switching is managed via the platform’s configuration system (settings.py), e.g.:

LLM_BACKEND = "gpt_oss_20b" LLM_ENDPOINTS = { "gpt_oss_20b": "http://localhost:8000/v1/chat/completions", "qwen3": "https://qwen.example/api", # … }

Adapters such as OllamaAdapter instantiate the selected LLM at runtime with system prompts defining available tools and expected schemas (2512.11935).

4. Materials-Science API Endpoints and Tools

AGAPI-Agents exposes more than twenty Pydantic-typed endpoints via FastAPI, covering the principal methods and data resources required for advanced computational materials science. Key endpoints include:

• /jarvis_dft/query: Structured queries to the JARVIS-DFT materials database, supporting complex boolean and numeric filters.
• /alignn/query: Graph neural network-based property prediction for input crystal structures, leveraging an MSE loss:

$$\mathcal{L}_\mathrm{MSE} = \frac{1}{N}\sum_{i=1}^N (y_i - \hat y_i)^2$$

• /alignn_ff/query: Machine-learning force-field-based geometry relaxations minimizing total potential under convergence criteria:

$$\min_\mathbf{R}\; E_\text{FF}(\mathbf{R}) \text{ with } \|\nabla E\|<\epsilon$$

• /generate_interface: Heterostructure construction (Zur algorithm).
• /pxrd/query: Powder X-ray diffraction simulation.
• /slakonet/bandstructure: Tight-binding Hamiltonian calculations:

$$H = \sum_{i\neq j} t_{ij}\,|i\rangle\langle j| + \sum_i \epsilon_i\,|i\rangle\langle i|$$

• /inverse_design: Target-driven materials generation constrained by compositional and structural requirements.

Tool schemas are enforced via Pydantic models, and registration for LLM awareness is managed via tool_registry.py and prompt templates (2512.11935).

5. Workflow Definition, Execution, and Extensibility

AGAPI-Agents supports workflow specification in Python or YAML/DSL, enabling fine-grained orchestration. Predefined pipelines include ten-step tasks (e.g., for defect engineering) that chain together database queries, structure manipulations, force-field relaxations, property predictions, band structure calculations, and result summarization. An example workflow construction and execution interface:

from workflows import Workflow, Step defect_analysis = Workflow(name="semiconductor_defect")\ .add_step(Step("jarvis_dft/query", args={"filter": …}))\ .add_step(Step("generate_supercell", args={"size":[2,2,2]}))\ .add_step(Step("substitute_atom", args={"from":"Ga","to":"Al","count":1}))\ # further steps omitted .finalize()

Agent-managed execution is invoked via AgentManager.run_workflow("semiconductor_defect"). Extension is standardized through the addition of new tool classes, accompanying Pydantic schemas, LLM prompt updates, and unit tests in the repository (2512.11935).

6. Reproducibility, Scalability, and Performance Evaluation

AGAPI-Agents emphasizes reproducibility and throughput:

• Deterministic sampling (temperature ≤ 0.1) and fixed random seeds (NumPy, PyTorch, Python).
• Request/response logging for all operations, enabling workflow replay.
• Async execution and batch submission, facilitating high-throughput queries.
• Automatic retry logic on HTTP and compute errors (up to $N=3$).

Performance benchmarks compare agentic predictions with and without tool access. For example, bulk modulus MAE decreases by 27% with tool integration (7.876→5.732 GPa, $R^2$ increases from 0.984 to 0.994), whereas bandgap MAE and some other properties degrade (bandgap MAE increases by 40% with tools, 0.353→0.495 eV; $T_c$ MAE increases by $5\times$ from 0.681 to 3.378 K) (2512.11935). This suggests that the efficacy of AGAPI workflows is property- and endpoint-dependent.

7. Installation, Deployment, and Community Contribution

Installation supports standard Conda environments (pip install agapi) and containerization (docker build -t agapi-server .). API authentication and endpoint redirection are configured via environment variables. Contribution is managed by a fork & pull request workflow, employing Black and flake8 for code style, and pytest for test coverage. New tools require Pydantic model definition, subclassing BaseTool, registry updates, modification of the LLM prompt schema, and independent unit tests.

AGAPI-Agents thus constitutes a scalable and modular foundation for reproducible, agentic AI-driven materials discovery, offering a unified access point to models, data, and simulation infrastructure across the domain (2512.11935).