---
title: AGAPI-Agents Codebase Overview
url: https://www.emergentmind.com/topics/agapi-agents-codebase
type: topic
---

# AGAPI-Agents Codebase Overview

AGAPI-Agents is an open-access agentic AI platform developed to accelerate and unify computational materials research by integrating multiple open-source large language models (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.:

```python
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:

```python
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].

Source: https://www.emergentmind.com/topics/agapi-agents-codebase