ARGI Examples

Examples for the ARGI core runtime and ARGI Extensions, organized as a Maven reactor: root project → capability group → independent example module. Only the sibling demo repository's directory and Maven aggregation layout was used. The implementations come from ARGI/Extensions API contracts and the scenarios in website/docs; no demo application source was reused.

The repository contains 59 executable example modules, with 12 additional backend profile configurations across the memory and vector modules. All nine website Graph scenario pages have dedicated examples. Website coverage maps chapters to relevant modules; a chapter mapping is not proof that every feature in that chapter is implemented. Behavioral coverage records the demonstrated paths, additional entry points, and limits of every module. catalog.json is the machine-readable source and scenario index.

Expanded scenarios separate application data, repositories, tools, state inspection, and workflow orchestration where they have distinct responsibilities. Small introductory examples remain small. Both production and test Java sources use explicit imports; the static catalog check rejects ordinary and static wildcard imports.

Requirements and setup

• JDK 17 or newer; Maven 3.9.1 or newer.
• ARGI and Extensions 2.1.0-RC2-SNAPSHOT built from compatible source revisions.
• Python 3 for staged dependency builds and the static catalog check.
• Model-backed examples need ARGI_API_KEY and ARGI_MODEL; ARGI_BASE_URL defaults to https://api.openai.com/v1. The Spring AI factory accepts ARGI_TIMEOUT_SECONDS (default 60); this validation used 120 for longer model turns.
• External integration examples need caller-managed services. Docker is required only by the optional Docker execution example or the chosen sandbox infrastructure.

Source checkouts are expected next to this repository:

open_source/
├── argi/
├── argi-extensions/
├── argi-example/
├── website/          # documentation input, not a build dependency
└── demo/             # structural reference, not a build dependency

Build dependencies from the revisions in compatibility.md, then install and run the selected module:

# Inspect source/document wiring; this does not execute Java or contact services.
python3 tools/check_catalog.py

# Install matching source dependencies without starting services or running tests.
bash tools/bootstrap.sh

# Install the example reactor; required by modules that reuse another example's factory.
bash tools/mvn.sh -B install

# Run a model-free example explicitly.
bash tools/run.sh argi-graph-example/hello-graph

tools/mvn.sh uses the installed mise-managed Java 17.0.19 and Maven 3.9.10 when mise is available; otherwise it uses your mvn. It does not install SDKs. Set ARGI_CORE_DIR and ARGI_EXTENSIONS_DIR if the source checkouts live elsewhere. The source revision and RC2 migration notes are in compatibility.md. The recoverable-runs module requires the pinned Core run/task-contract commit; an older RC2 snapshot with the same Maven version does not contain those classes.

The root imports both argi-bom and argi-extensions-bom, with the Core BOM first. The bootstrap command overrides Extensions' RC1 default with the matching RC2 core version. It builds temporary source copies with three compatibility corrections documented in compatibility.md, then removes those copies. Sibling tracked source files are never modified. All examples use io.github.agentic.ai.* and neutral model/tool contracts at the ARGI runtime boundary.

Example catalog

Runtime labels: local needs no model or service; model uses real provider credentials; service needs the external service described in its README and may also need a model. Tests use local fixtures where provided; sample main methods use real APIs rather than mock responses.

argi-adapter-example

Example	Runtime	Demonstrates
agentscope	model	Wraps an AgentScope OpenAI-compatible model in the neutral ARGI ChatClient.
google-adk	model	Uses the Google ADK Apigee OpenAI-compatible transport through an ARGI adapter.
langchain4j	model	Wraps LangChain4j chat and streaming models in the neutral ARGI ChatClient.
spring-ai	model	Wraps a Spring AI OpenAI-compatible model in the neutral ARGI ChatClient.

argi-agent-example

Example	Runtime	Demonstrates
a2a	service	Discovers a remote A2A agent card and delegates a task over the A2A protocol.
agent-as-tool	model	Registers a specialist as a neutral Tool, letting a coordinator delegate work.
agent-hitl	model	Pauses tool calls and accepts approved, rejected, or edited human feedback.
agentic-rag	model	Makes retrieval an agent tool and adds evidence through a MessagesModelHook.
builtin-tools	model	Registers built-in filesystem, search, and todo tools with neutral bindings.
context-compaction	model	Uses SummarizationHook to bound model context while retaining recent turns.
context-engineering	model	Preserves per-thread conversation history and enforces model call budgets.
hooks-and-retries	model	Combines PII redaction, model/tool budgets, and bounded retries for read-only tools.
interceptors	model	Custom model and tool interceptors measure duration and cache a read-only lookup.
multi-agent	model	Parallel reviewers feed sequential writing and a bounded revision loop.
planner	model	Produces validated direct or decomposed plans from an explicit capability catalog.
react-tools	model	Runs a ReAct tool loop against a local order-tracking catalog.
routing-streaming	model	Uses LLM routing to choose a specialist and demonstrates neutral streamed messages.
skills	model	Loads packaged skills, decorates neutral prompts, and exposes progressive skill disclosure.
structured-output	model	Requests a JSON schema and validates the parsed domain record.
studio-chatbot	model	Publishes a stateful agent bean through the embedded ARGI Studio.
support-workflow	model	Embeds a ReAct writer in a deterministic support workflow with human review.

argi-extensions-example

Example	Runtime	Demonstrates
a2a-nacos	service	Resolves an A2A agent by registered name in Nacos before delegation.
docker-execution	service	Executes a fixed Python calculation through the Extensions Docker code executor.
document-parsing	local	Parses UTF-8 text and JSON records while preserving source metadata.
http-node	service	Retrieves an HTTP order resource as a graph step with explicit timeout and network policy.
jdbc-chat-memory	local	Persists a bounded Spring AI conversation with the Extensions H2 repository.
jdbc-checkpoint	local	Restores a pending approval through an H2 JDBC checkpoint saver and a new graph.
mcp-client	service	Initializes a Streamable HTTP MCP client and enumerates all tool pages.
mcp-discovery	service	Discovers registered MCP tools through Nacos and adapts callbacks for ReAct.
mcp-gateway	service	Aggregates Nacos MCP services into independently routed SSE and Streamable endpoints.
mcp-registry	service	Publishes a read-only MCP tool and registers the server in Nacos.
mcp-router	service	Exposes semantic MCP routing tools to a neutral ARGI agent.
mem0-memory	service	Writes semantic memories to Mem0 and retrieves them with an explicit user scope.
memory-backends	service	Profile-selected Redis, MongoDB, Elasticsearch, TableStore, Memcached, and JDBC chat repositories.
mongodb-checkpoint	service	Persists neutral graph state in the Extensions MongoDB checkpoint saver.
nacos-prompt	service	Loads and watches a configurable prompt through Nacos and the Extensions prompt factory.
rag-retrieval	service	Expands a query with HyDE and retrieves evidence through the RAG graph node.
redis-checkpoint	service	Stores and reloads neutral graph checkpoints with the Extensions Redis saver.
sandbox-tools	service	Adapts an Extensions sandbox Python tool into a neutral ReAct agent.
tair-vector-store	service	Writes real embeddings to a Tair Vector index and searches for relevant documents.
vector-backends	service	Profile-selected AnalyticDB, OceanBase, OpenSearch, TableStore, and Tair indexing and search.

argi-graph-example

Example	Runtime	Demonstrates
cancellation	local	Cancels exactly one graph subscription and releases its asynchronous worker.
conditional-routing	local	Routes support tickets into urgent and normal queues using conditional edges.
hello-graph	local	A two-step model-free workflow that normalizes a name and creates a greeting.
hitl	local	InterruptableAction requests missing feedback and resumes the same node.
human-in-the-loop	local	Pauses before a refund decision and resumes from the same checkpoint.
observation	local	Records graph observations with a local Micrometer handler and no telemetry backend.
parallel-nodes	local	Fork/join branches, an append reducer, explicit executors, and streamed node output.
parallel-subgraph	local	Joins order checks and creates a receipt in a nested graph.
persistence	local	File checkpoints, thread identity, history inspection, and recovery with a fresh graph.
plantuml	local	Exports PlantUML and Mermaid representations without invoking the graph.
runtime-store	local	Separates transient invocation metadata, thread state, and long-lived namespaced memory.
recoverable-runs	local	Run/task admission, deduplication, leases, revision conflicts and atomic checkpoint/journal/outbox writes.
scheduling	local	Schedules a graph at a fixed delay and shuts down the task manager after completion.
spring-ai-integration	model	Adapts a Spring AI model into a neutral streaming LlmNode and consumes graph events.
state-serialization	local	Append and replace reducers plus neutral message serialization round trips.
subgraph-as-compiled-graph	local	Embeds a compiled child directly and demonstrates reusable state transformation.
subgraph-as-node	local	Explicitly maps parent input/output to a child graph with private state.
subgraphs	local	A StateGraph subgraph shares parent state and produces a normalized invoice.

Running model and service examples

Inject credentials through your shell or credential manager. Do not put them in source files, Maven command arguments, or committed .env files. For example, after configuring your environment:

bash tools/run.sh argi-agent-example/react-tools
bash tools/run.sh argi-agent-example/studio-chatbot

Studio serves /chatui/index.html on port 8080 and discovers the studio_support agent bean. SERVER_PORT overrides the port. Studio uses the upstream bundled UI; this repository does not copy a demo frontend.

The memory/vector backend modules select one starter at a time. Match the Maven profile (dependency selection) and Spring profile (configuration selection):

bash tools/run.sh argi-extensions-example/memory-backends \
  -Pmemory-redis -Dexec.args=--spring.profiles.active=redis

bash tools/run.sh argi-extensions-example/vector-backends \
  -Pvector-oceanbase -Dexec.args=--spring.profiles.active=oceanbase

Their READMEs list every backend and required environment variable configuration. Provision external services separately. No repository command starts OrbStack, Docker, Nacos, Redis, MongoDB, Elasticsearch, Tair, or a model server.

The MCP modules demonstrate this composition:

1. mcp-registry publishes the read-only lookup tool and registers argi-catalog in Nacos.
2. mcp-client connects directly; mcp-discovery resolves it through Nacos.
3. mcp-router exposes semantic service-routing tools to a ReAct agent.
4. mcp-gateway exposes independently routed Streamable and SSE endpoints.

Each component has its own port/configuration and is started explicitly by its caller.

Checks and CI

# Static inventory and document links only.
make catalog

# Optional compilation without tests or sample execution.
make compile

# Optional tests and JaCoCo verification; never starts external infrastructure.
make verify

Local execution was authorized and performed on 2026-10-15, using the selected Claude Code model (sonnet resolved to glm-5.3) through its OpenAI-compatible gateway. Credentials were passed only through child-process environments; neither the settings file nor credentials were copied into this repository. The normal examples continue to use ARGI_API_KEY, ARGI_MODEL and ARGI_BASE_URL.

The full reactor and all 12 backend profiles build successfully. All 109 local tests and all 36 local entry-point runs pass. Of 38 real-model cases, 34 pass and four remain incomplete after gateway resets/timeouts. Studio HTTP/SSE also passed. The 90% JaCoCo line threshold remains enabled for bundles with execution data; modules without tests are explicitly outside the measured percentage. Compatibility and validation results record exact counts, failed gateway requests and unexecuted external-service scenarios. No database, Nacos, MCP server, Docker daemon or sandbox infrastructure was started. Performance, load, capacity, chaos, dependency-vulnerability and remote-CI checks are not claimed by this local execution.

GitHub Actions keeps CI enabled for pushes and pull requests. It installs pinned upstream source revisions, verifies the examples, and compiles every backend profile. CI is enabled; the current working-tree changes have not been validated by a remote run. No CI result is inferred from source inspection.

Adding an example

Add a capability-focused module, a Java main entry point, a README with prerequisites and observable results, and tests for nontrivial local behavior. Register the module in its group POM and update docs/catalog.json, docs/website-coverage.md, and docs/feature-coverage.md. Register all supporting sources, tests, and additional main methods in the catalog, with their demonstrated behavior and limitations. Use a real integration in integration scenarios. Label local corpora, fault injection, and emulation explicitly; keep mock providers in src/test. Do not use wildcard imports.

Cleanup and rollback

Generated diagrams, checkpoints, workspaces, and reports live under each module's target/. They can be removed after inspection. External-service examples document which sample records they retain; never clear an entire production store to clean up an example. This is a new repository, with no migration of existing application data. Remove or revert these new files to roll back the authoring changes. Sibling repository source files are not part of this change.

License

Apache License 2.0.