SamurAI 1.0 • Java 17+ • Zero dependencies

AI agents in plain Java

SamurAI automates business processes with AI agents — from ticket triage to document processing and approvals. Pipelines run in plain Java with zero runtime dependencies, talk to 31 LLM provider types, prefer free tiers and keep a ledger of every token you spend.

▶ Try the simulation Get started GitHub

BUSINESS AUTOMATION

Put repetitive work on autopilot

AI agents handle the judgment calls, deterministic steps handle the rest, and people approve what matters.

🎫

Ticket & email triage

Classify incoming requests, extract key data, set priority and send each one to the right team.

📄

Document processing

Read invoices, contracts and forms, extract the fields you need and validate them against your rules.

✅

Approval workflows

Route refunds, purchases or exceptions to a person, pause until they decide, then continue automatically.

📊

Scheduled reports

Collect data from APIs and databases on a schedule and turn it into readable summaries and alerts.

🔗

System integration

Move and reconcile data between CRMs, ERPs and internal tools via HTTP calls and Java functions.

🚨

Operations monitoring

Check servers and services, diagnose incidents and draft the report — see the live triage demo below.

FEATURES

Everything an agent system needs

No vendor lock-in, no runaway token bills, no dependency tree to audit.

🌐

31 LLM provider types

OpenAI, Claude, Gemini & Vertex AI, DeepSeek, Groq, Bedrock, Azure, Mistral, xAI, local Ollama / LM Studio / vLLM / llama.cpp, plus Claude Code and Gemini CLI subscriptions.

💰

OPTIMAL cost routing

Free tiers and local models first, quota tracking, purpose-based routing and cascade escalation to paid models only when needed. Circuit breaker included.

⚙️

Blind agents ($0)

CommandAgent, HttpAgent, FunctionAgent and WaitAgent run deterministic steps without calling an LLM.

📜

XML workflows

Declare agents, routers, parallel branches, schedules and approvals in samurai.xml, validated by an XSD. No compilation.

✋

Human in the loop

Approval gates pause a pipeline until a person approves or rejects — from Studio, the web UI or a REST call.

🔌

Studio & MCP server

Desktop and web Studio with live SSE streaming; expose any workflow as an MCP tool for Claude Code, Cursor or Antigravity.

INTERACTIVE DEMOS

Watch a pipeline run, read its source

Simulated runs of two real SamurAI applications, next to the Java or XML that defines them.

📄 IncidentWorkflow.java

COMPARE

SamurAI vs. other agent frameworks

Aspect	SamurAI	LangChain4j	Spring AI	Python (LangChain / CrewAI)
Runtime dependencies	None	Many transitive JARs	Spring ecosystem	Many pip packages
Cost optimization	Built-in, free tier first	Manual	Manual	Manual
Steps without LLM	Native blind agents	Via tools	Via tools	Via tools
Declarative workflows	XML + XSD	Code only	Code / config	Code / YAML
Human approvals	Native	Custom	Custom	Custom
Tooling	Studio, web UI, MCP server	Library	Actuator	Third-party

GET STARTED

From zero to a running pipeline

Add the core JAR

Put samurai-core-1.0.jar on the classpath, or declare ro.softway:samurai-core:1.0. Java 17+ is all it needs.
Configure providers

Set API keys in .env or system properties. Local Ollama instances and free-tier models are detected automatically and used first.
Run a workflow
```
java -jar samurai-xml-1.0-all.jar run app.xml <flow>
```
Or build the same pipeline in Java with the core API.
Open Studio or connect via MCP
```
java -jar samurai-studio-1.0-all.jar serve
```
Watch runs live, approve gated steps, or register the MCP server in Claude Code / Cursor.

More technical details Source code, provider setup, XML schema reference and more workflow examples. github.com/Ste3fan/samurAI

FAQ

Frequently asked questions

What is SamurAI?

SamurAI is a Java framework by SoftWay for building and orchestrating AI agents. The core has zero external runtime dependencies and runs on Java 17+.

Can SamurAI automate business processes?

Yes. SamurAI pipelines combine AI steps with deterministic ones (HTTP calls, commands, Java functions) to automate processes such as ticket triage, document and invoice processing, request routing with approvals, scheduled reports and data synchronization between systems. Approval gates keep a person in control of sensitive decisions, and every run is logged with its cost.

Which LLM providers does SamurAI support?

31 provider types, including OpenAI, Anthropic Claude, Google Gemini and Vertex AI, DeepSeek, Groq, AWS Bedrock, Azure, Mistral, xAI, local runners (Ollama, LM Studio, vLLM, llama.cpp) and subscription CLIs such as Claude Code and Gemini CLI.

How does SamurAI keep LLM costs down?

The OPTIMAL strategy prefers free tiers and local models, tracks quotas, escalates to paid models only on failure, and runs deterministic steps with blind agents that make no LLM calls. A cost ledger reports spend per model or orchestrator.

Can I define workflows without writing Java?

Yes. Applications, flows, schedules and approval gates can be declared in samurai.xml, validated by an XSD, and run from the command line or SamurAI Studio.

Does SamurAI work with Claude Code or Cursor?

Yes. The built-in MCP server exposes SamurAI workflows and agents as Model Context Protocol tools for Claude Code, Cursor, Google Antigravity and other MCP clients.