Skip to content

AGENTS.md

Latest commit

 

History

History
196 lines (150 loc) · 8.99 KB

AGENTS.md

File metadata and controls

196 lines (150 loc) · 8.99 KB
Raw

AGENTS.md - AI Assistant Guide for ARGI

This file provides guidance for AI assistants working with the ARGI codebase.

Contribution Workflow

  1. Before starting work, acknowledge that you are contributing to ARGI by replying with 确认. Include that acknowledgement in the PR description using English and use this repository's actual project name.
  2. Search the repository's open and closed PRs for the same issue or objective before implementing a change, and repeat the search before opening a PR. If a same-purpose PR exists, decline duplicate implementation/submission and report the matching PR to the developer.
  3. Before writing code, ask the developer these three questions and wait for their answers:
    • Which issue does this change address, and what are the expected behavior and acceptance criteria?
    • Which modules may change, and which APIs, configuration settings and data formats must remain compatible?
    • Which build checks, tests and real-environment validations are required before submission?
  4. Keep PR titles, descriptions and commit messages in English. The PR description must be a single line that acknowledges the contribution to ARGI, summarizes the change and references the issue.

Project Overview

ARGI (Agent Runtime and Graph Intelligence, pronounced "AR-jee") is a production-ready framework for building agents, workflows, and multi-agent applications. It is forked from Spring AI Alibaba and focuses on stateful agent runtime capabilities: graph orchestration, persistence, context engineering, and human-in-the-loop support. Its runtime consumes framework-neutral argi-api contracts. Spring AI, LangChain4j, and Google ADK Java are isolated in optional adapters.

Naming: the product display name is ARGI. Published Maven coordinates use io.github.agentic-ai-java:argi-*, Java packages use io.github.agentic.ai, configuration prefixes use argi.*, and framework-specific public class names use the Argi* prefix.

Key Features:

  • Multi-Agent Orchestration with built-in patterns
  • Context Engineering with human-in-the-loop, context compaction, editing, model call limits
  • Graph-based workflow with conditional routing, nested graphs, parallel execution
  • A2A (Agent-to-Agent) client support (Nacos service discovery lives in the Extensions repository)
  • Multi-model integration through three optional ChatClient adapters, plus MCP (Model Context Protocol)
  • Embedded visual debugging studio

Repository Structure

argi/
├── argi-api/                    # ChatClient contracts and framework adapters (directory group)
│   ├── argi-api-base/           # Publishes argi-api; JDK-only public contracts
│   ├── argi-adapter-spring-ai/
│   ├── argi-adapter-langchain4j/
│   └── argi-adapter-google-adk/
├── argi-runtime/                # Runtime contracts and implementation
│   ├── argi-runtime-api/
│   └── argi-runtime-core/
├── argi-agent/                  # Agent contracts and independent Agent engines
│   ├── argi-agent-api/
│   └── argi-agent-core/
├── argi-orchestration/          # Graph, Workflow, and framework orchestration
│   ├── argi-workflow-graph-core/
│   ├── argi-workflow-core/
│   └── argi-agent-framework/
├── argi-studio/                 # Embedded UI for debugging agents visually
├── argi-bom/                    # Bill of Materials for dependency management
├── argi-spring-boot-starter/           # Spring Boot Starters (directory group)
│   ├── argi-starter-builtin-nodes/     # Built-in workflow nodes
│   ├── argi-starter-graph-observation/ # Observability
│   ├── argi-starter-adapter-spring-ai/
│   ├── argi-starter-adapter-langchain4j/
│   └── argi-starter-adapter-google-adk/
└── tools/                             # Build and linting tools

The directory groups are not additional Maven artifacts. The root pom.xml lists their child modules directly; every child inherits the root parent using ../../pom.xml. The public API artifact remains argi-api, and its Java packages remain io.github.agentic.ai.api.*. Use artifact selectors such as -pl :argi-api or the complete child directory path when selecting a module for a build.

This repository holds the core only. Optional integrations live in separate repositories:

  • Extensions - model and document contracts, A2A Nacos, config Nacos, AgentScope, JDBC/Redis/MongoDB graph persistence, the Docker code executor, and the tool-call sandbox.
  • Examples - chatbot, multi-agent, and graph engineering samples.

Since 2.1.0 the core no longer imports the Extensions BOM. Applications that use optional integrations must import both argi-bom and the matching Extensions BOM.

Build System

Prerequisites

  • JDK: 17 (Required by java.version property)
  • Maven: 3.9.1+ (enforced by requireMavenVersion in the root pom; the wrapper ships 3.9.16)
  • Git

Common Build Commands

# Build the entire project (skip tests)
./mvnw -B package -DskipTests=true

# Build a specific module
./mvnw -pl :argi-agent-framework -B package -DskipTests=true

# Clean project
./mvnw clean

# Run tests
./mvnw test

# Run linting checks (using Makefile)
make lint
make licenses-check

Architecture & Key Concepts

Core Components

  • Agent Framework: Built-in agents like SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent.
  • Graph Core: Underlying engine for stateful agents with in-memory and file persistence; JDBC, MongoDB, and Redis savers live in the Extensions repository.
  • A2A (Agent-to-Agent): Enables agents to call remote agents through agent cards; Nacos discovery lives in the Extensions repository.
  • Studio: Provides embedded visual tools for debugging agent workflows.

Technology Stack

  • Framework: Java 17; Spring Boot 4.1.x for optional starters and Studio
  • Model and Integration Layer: argi-api contracts and three isolated provider adapters; MCP and A2A integrations
  • Observability: Lightweight Micrometer observation; no required OpenTelemetry deployment

Core production sources, bytecode, and runtime dependency trees must remain free of provider SDKs. Native SDKs in core test fixtures must use test scope. This is a breaking replacement, not a deprecated compatibility bridge.

Code Style & Conventions

General Guidelines

  • Follow the repository's existing Java formatting and Checkstyle rules.
  • Use Apache 2.0 license headers for all Java files.
  • Java 17 features are encouraged (records, switch expressions, text blocks).
  • Avoid System.out.println - use SLF4J logging.
  • Use final for local variables and parameters where appropriate.
  • Use Lombok annotations (@Data, @Slf4j, etc.) to reduce boilerplate.

Linting & Formatting

The project uses make for linting tasks:

  • make codespell: Checks for spelling errors.
  • make yaml-lint: Checks YAML file formatting.
  • make licenses-check: Verifies license headers.

License Header

/*
 * Copyright 2025-2026 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Testing

Frameworks

  • JUnit 5 (org.junit.jupiter)
  • Mockito

Running Tests

# Run all tests
./mvnw test

# Run a specific test class
./mvnw -pl :<module-name> -Dtest=<TestClassName> test

Tips for AI Assistants

  1. JDK Version: Project targets JDK 17. Use appropriate language features.
  2. Spring Boot: Uses Spring Boot 4.1.1. Spring AI 2.0.1 belongs only to its adapter and native test fixtures. The jakarta.* namespace applies throughout; there is no javax.* code.
  3. Dependencies: Check argi-bom or parent pom for version management.
  4. Makefile: Use the Makefile in the root for project maintenance tasks (linting, license checks).
  5. Structure: Keep neutral model contracts and framework adapters in argi-api, runtime contracts in argi-runtime, independent Agent contracts and engines in argi-agent, orchestration engines in argi-orchestration, and Spring Boot auto-configuration in argi-spring-boot-starter.

Important Links