DOCSEARCHbyAlgolia
Submit Docs

Solon-AI Documentation

repository·main·Indexed 19 days ago

https://github.com/opensolon/solon-ai

A comprehensive Java framework for developing LLM-powered applications, including Autonomous Agents, RAG systems, and multi-agent collaborative workflows. It integrates modern AI protocols like MCP and provides the acp-agent-support module for building ACP agents using a declarative, annotation-based programming model (@AcpAgent, @Prompt, @Initialize). Features include a unified interface for model providers, SyncPromptContext for agent-client interaction, and support for Stdio, WebSocket, and InMemory transports.

Tokens
76.4K
Snippets
174
Records
269
Agent score
65%

What's inside Solon-AI

  1. Overview of solon-ai-sandbox

    main

    solon-ai-sandbox

    solon-ai-sandbox is the security isolation module within the Solon AI ecosystem. It provides cross-platform (macOS, Linux, Windows) isolation for file systems, networks, and processes specifically designed for executing AI Agent code safely.

    It is a Java port of Claude Code's sandbox-runtime (originally TypeScript) and provides an embeddable sandbox runtime.

    Core Capabilities

    • File System Isolation: Uses deny-then-allow-back (for reading) and allow-only (for writing) strategies to precisely control process access.
    • Network Isolation: Built-in HTTP/SOCKS5 forward proxies with support for domain allow/deny lists and real-time dynamic rule updates.
    • Cross-Platform Support:
      • macOS: Uses sandbox-exec + Seatbelt configurations.
      • Linux: Uses bubblewrap (bwrap) + seccomp.
      • Windows: Uses srt-win.exe + WFP.
    • Interactive Authorization: Provides the SandboxAskCallback interface to prompt users when a network request does not match existing rules.
    • Violation Tracking: SandboxViolationStore thread-safely records all sandbox violations, supporting category-based filtering.
    • Parent Proxy Support: Supports upstream HTTP/HTTPS proxies (via HTTP_PROXY etc.) and NO_PROXY CIDR/domain matching.
    • Real-time Configuration Updates: Network allow-lists support hot-updates without restarting the proxy server.

  2. Overview of Solon AI Loop Engine

    main

    The Solon AI Loop Engine is a task execution engine designed to provide persistent, orchestratable, and verifiable task loops for the Solon AI ecosystem. It is deeply integrated with solon-flow (flow orchestration), solon-ai-agent (intelligent agents), and solon-ai-harness (tool management).

    Key Features

    • Multiple Loop Strategies: Supports Ralph (PRD-driven story loops), Team Pipeline (multi-stage pipelines), and UltraQA (quality gate loops).
    • Full State Machine: Manages transitions through states: IDLE → PLANNING → EXECUTING → VERIFYING → FIXING → COMPLETED/FAILED. Supports pausing and resuming.
    • State Persistence: Offers both in-memory and disk-based JSON persistence (using atomic writes) to support recovery across processes.
    • Verification Framework: Includes a Validator interface, QualityGate quality gates, and dual verification via Architect/Critic patterns.
    • Strategy Mutual Exclusion: Uses MutualExclusionGuard to ensure that Ralph, UltraQA, and Team Pipeline strategies do not run simultaneously.
    • Autopilot Orchestration: A multi-stage pipeline orchestrator that allows registering custom StageAdapter implementations.
    • Monitoring & Debugging: LoopMonitor collects runtime metrics, and LoopDebugger tracks event logs.

  3. What is solon-ai-harness?

    main

    solon-ai-harness is the core orchestration container for the Solon AI framework. It provides the complete infrastructure for AI agents, including the Agent runtime, sub-agent scheduling, command systems, and security policies.

    It acts as a capability integrator. The HarnessEngine instantiates and configures over 20+ 'Talents' (components) provided by various Maven dependency packages. Using AgentFactory.create(), it selectively injects these components into a ReActAgent based on the tool permissions defined in an AgentDefinition, resulting in a fully capable AI agent.

  4. Overview of solon-ai-ui module

    main
    The solon-ai-ui module bridges the gap between backend AI applications (Agents, LLM programs) and frontend interfaces. It solves the problem of communication protocols—specifically how to display AI outputs and the format for Server-Sent Events (SSE) transmission. It achieves this by providing standardized protocol adapters for mainstream industry UI protocols or offering frameworks for rapid integration.

  5. Overview of acp-core key classes

    main

    The acp-core library provides the fundamental building blocks for implementing the Agent Client Protocol in Java. It includes support for both synchronous and asynchronous (Project Reactor-based) communication, protocol type definitions, and stdio-based transport.

    | Class | Purpose |
|-------|---------|
| `AcpClient` | Factory — `AcpClient.sync()` and `AcpClient.async()` |
| `AcpAgent` | Factory — `AcpAgent.sync()` and `AcpAgent.async()` |
| `AcpSchema` | All protocol types (requests, responses, updates) |
| `StdioAcpClientTransport` | Launches agent as subprocess, communicates over stdin/stdout |
| `StdioAcpAgentTransport` | Reads from stdin, writes to stdout |

  6. Overview of Solon AI Harness modules and responsibilities

    main

    The solon-ai-harness project is organized into several functional modules:

    ModulePackage/ComponentResponsibility
    Engine CoreHarnessEngineOrchestrates external dependencies, manages configuration, and handles Talent injection.
    Extension PointHarnessExtensionSPI for injecting custom logic during agent construction.
    ConfigurationHarnessOptionsRuntime configuration for paths, feature toggles, retry strategies, and windowing.
    Agent Definitionagent.AgentDefinitionMetadata model for agents (name, description, tools, permissions, models, MCP, memory).
    Agent Factoryagent.AgentFactoryConstructs ReActAgent instances by mapping tool names to engine components.
    Agent Managementagent.AgentManagerDiscovery, caching, and lifecycle management of built-in and mounted agents.
    Sub-agent Schedulingagent.TaskTalentDelegates tasks (serial or parallel) to specialized sub-agents.
    Dynamic Creationagent.GenerateTalentCreates new sub-agent definitions at runtime (can be persisted to files).
    Command Systemcommand.*Shared command framework for CLI and Web, supporting Markdown-based custom commands.
    IM Channelschannel.ChannelUnified interface for messaging platforms (WeChat, Feishu, DingTalk, etc.).
    Security/Audithitl.BashToolStrategyIntervention strategy for Bash tools (defense, read-only classification, rule engine).
    Permissionspermission.ToolPermissionManages the three-tier shorthand permission system (pi, *, **).

  7. Overview of Solon AI

    main

    Solon AI is a comprehensive Java-based AI development framework designed for building LLM-powered applications. It integrates Large Language Models (LLM), Retrieval-Augmented Generation (RAG), the Model Context Protocol (MCP), and Agent orchestration (ReAct, Team-based).

    Key features include:

    • Multi-model support: A unified ChatModel interface that adapts to various providers like OpenAI, Gemini, Claude, Ollama, DeepSeek, and Dashscope.
    • Graph-driven orchestration: Converts Agent reasoning into observable and manageable computational flow graphs.
    • Framework compatibility: Works natively with the Solon ecosystem and can be seamlessly embedded into SpringBoot, Vert.X, or Quarkus.

  8. Explore Solon ecosystem repositories

    main

    The Solon ecosystem consists of several specialized repositories. Depending on your needs, you can explore the core framework, AI-specific modules, flow engines, or development plugins.

    Core & AI Modules

    • solon: The main Solon framework repository.
    • solon-ai: The Solon AI code repository.
    • solon-flow: The Solon Flow code repository.
    • solon-expression: The Solon Expression code repository.
    • solon-cloud: The Solon Cloud repository.
    • solon-admin: The Solon Admin repository.
    • solon-integration: The Solon Integration repository.

    Java Runtime Versions

    • solon-java17: Solon base for Java 17.
    • solon-java25: Solon base for Java 25.

    Specialized Tools

    • soloncode: Java 8 implementation of "Claude Code".
    • solonclaw: Java 8 implementation of "OpenClaw".

    Build & IDE Plugins

    • solon-maven-plugin: Maven plugin.
    • solon-gradle-plugin: Gradle plugin.
    • solon-idea-plugin: IntelliJ IDEA plugin.
    • solon-vscode-plugin: VS Code plugin.

  9. Understand the solon-ai-harness project structure

    main

    The project is composed of 14 internal source files and 9 integrated dependency packages.

    Core Modules

    • HarnessEngine: The central engine using the Builder pattern to orchestrate all components.
    • AgentFactory: Creates agents by mapping tool names to Talents registered in the engine.
    • AgentDefinition: Metadata model for agents, driven by YAML frontmatter.
    • Command System: A unified framework for CLI and Web command execution.
    • HITL (Human-In-The-Loop): Security strategies for Bash, Web, and File writing tools (e.g., BashToolStrategy, WriteToolStrategy).
    • Talents: Specialized capability providers (e.g., CodeTalent, WebsearchTalent, MemoryTalent).

    Key Maven Coordinates

    • Engine: org.noear:solon-ai-harness

  10. How ContextCompressionInterceptor works

    main

    The ContextCompressionInterceptor manages the conversation context to prevent exceeding model token limits. It executes during the onReasonStart phase of an agent's reasoning cycle.

    Execution Flow:

    1. MicroCompact Guard: Truncates individual messages exceeding perMessageCap (retaining head and tail).
    2. Threshold Check: Compares current tokens against finalTokenThreshold (calculated as contextLength * maxContextLengthRatio). If within limits, no compression occurs.
    3. First Principles Extraction: Collects all messages marked with AgentTrace.META_FIRST (e.g., System Prompts, User Goals) to ensure they are never lost.
    4. Budget Calculation: Reserves a portion of the available tokens for a summary and a 'retention window'.
    5. Truncation & Alignment: Determines a truncation point based on both message count and token budget. It ensures Assistant(with tool_calls) and ToolMessage pairs are kept together (Atomic Pair Protection).
    6. Reconstruction: Rebuilds the WorkingMemory using the preserved 'First Principles', the compressed summary (if a strategy is provided), and the recent retention window.
    7. Cleanup: Removes dangling tool outputs and filters 'empty shell' AssistantMessage objects (messages with no content or tool calls) to prevent API 400 errors.

  11. Ralph Loop Strategy (PRD-driven)

    main

    The RalphLoopStrategy is designed for PRD (Product Requirement Document) driven development. It extracts user stories from a PRD and implements them one by one, verifying each with an Architect and Critic before moving to the next. It records progress (implementations, file changes, lessons learned) via a ProgressManager.

    Use this when you want to automate the implementation of a set of requirements defined in a document.

    RalphLoopStrategy strategy = RalphLoopStrategy.builder()
    .verificationRequired(true)
    .criticMode("architect")     // architect / critic / none
    .maxIterations(50)
    .storyImplementor((story, ctx) -> { /* Custom implementation logic */ })
    .storyValidator((story, result, ctx) -> { /* Custom validation logic */ })
    .build();

  12. Configure an Agent Profile

    main

    An Agent Profile acts as the agent's identity, defining its behavioral boundaries. It supports:

    • Dynamic Descriptions: Use placeholders like #{platform} which are rendered from the session context.
    • Capabilities: Explicitly declare expertise (e.g., talentAdd) and supported modalities.
    • Constraints: Hard rules via constraintAdd (e.g., "Do not use exclamation marks").
    • Style: Define language tone (e.g., "Minimalist").
    SimpleAgent blogger = SimpleAgent.of(chatModel)
    .name("blogger")
    .description("负责 [#{platform}] 平台的文案创作") // 动态占位符
    .profile(p -> p
        .talentAdd("爆款标题制作", "小红书风写作")
        .constraintAdd("必须包含 Emoji", "严禁使用感叹号")
        .style("活泼亲切")
        .metaPut("version", "1.0.2"))
    .build();