AgentScope Java – 企業級代理框架

1. 專案概覽

AgentScope Java 是一個生產就緒的 Java 框架，用於建構分散式、企業級的 AI 代理，內建支援長時間執行且安全受控的運作方式——它將代理開發從原型製作推進到可營運的多租戶生產環境。

2. 背景與定位

核心使命：大多數代理框架只專注於讓單一代理在示範中「運作」。AgentScope Java（2.0 版）的誕生是為了填補可用原型與能在生產環境中可靠運作的系統之間的差距——將可觀測性、權限控管、沙箱隔離與分散式工作階段復原視為首要考量，而非事後補救。
與類似專案的差異：AgentScope Java 不只是 LLM 呼叫的輕量包裝層，而是在經典的 ReAct（推理-行動）迴圈之上疊加了一層「控制框架」——加入中介軟體掛鉤、型別化事件串流、人機協作審核關卡，以及可插拔的沙箱（本機、Docker、Kubernetes 或雲端）。它原生為 JVM 生態系設計，對於已經運行 Java/Spring 後端基礎設施、且希望在既有生態系內獲得企業級代理能力的團隊來說，是相當自然的選擇。

3. 功能類別

⚙️ 基礎框架 — 建構代理的核心原語。代表性範例：28 種用於串流代理狀態的型別化事件、統一內容區塊（文字/檔案/圖片/音訊/影片）、ReAct 執行迴圈，以及將人機協作視為內建互動模式。目的：為開發者提供一致且型別化的代理行為詞彙，取代臨時拼湊的 JSON 承載。
🧩 控制框架工程 — 疊加在核心迴圈之上的中介軟體。代表性範例：自我演進的技能庫、分層記憶（對話歷史 + 精選 Markdown + 事實紀錄）、子代理生成、自動上下文管理，以及用於多步驟任務的「計畫模式」。目的：在不修改核心框架程式碼的情況下，擴充與自訂代理的推理和行動方式。
🏢 企業部署 — 大規模運行代理的能力。代表性範例：多租戶隔離、安全沙箱、細粒度權限控管，以及跨副本的工作階段復原以支援零停機滾動更新。目的：讓代理在真實生產流量下安全且具韌性地運行。
🔌 整合 — 與外部世界連結的模組化連接器。代表性範例：LLM 供應商（OpenAI、Anthropic、DashScope、Gemini、DeepSeek、Ollama）、企業即時通訊管道（釘釘、飛書、企業微信），以及互通性協定（A2A、AG-UI）。目的：讓代理無需自訂黏合程式碼即可接入現有的模型供應商與通訊工具。
💾 狀態與持久化 — 用於儲存代理與工作階段狀態的後端。代表性範例：記憶體、JSON 檔案、MySQL、Redis 與 PostgreSQL。目的：讓代理在重新啟動或跨副本時能恢復狀態。

4. 重點特色

型別化事件串流 — 28 種不同的事件類型讓前端與編排器能即時、精確且結構化地掌握代理正在進行的動作，而非解析自由文字日誌。
內建人機協作設計 — 權限系統讓操作者可以在個別工具呼叫執行前選擇性地核准或拒絕，這對於可能採取真實世界動作的代理至關重要。
基於中介軟體的可擴充性 — AOP 風格的掛鉤在五個不同階段攔截推理-行動迴圈，讓團隊可以加入日誌、護欄或自訂邏輯，而無需分叉核心。
彈性沙箱 — 工具執行可以在本機、Docker、Kubernetes 或 AgentRun 雲端環境中隔離，讓隔離等級與工作負載的敏感度相匹配。
多代理編排 — 原生 agent_spawn 與 agent_send 原語支援子代理模式，並在父代理與子代理之間即時轉發事件。
分散式工作階段復原 — 工作階段狀態可以透過 Redis、MySQL、PostgreSQL、OSS 或 COS 作為後端儲存，在副本重新啟動與滾動部署期間存活。

5. 依角色區分的使用案例

一般開發者：直接在 Java/Spring 應用程式中使用熟悉的 Maven 依賴來建構代理功能（聊天機器人、任務自動化、使用工具的助理），無需橋接到 Python 服務。
DevOps/SRE：自信地在滾動更新後部署代理，因為工作階段狀態與進行中的任務可以在副本之間復原，不會在重新部署時遺失。
專案經理：使用權限系統與事件串流，對敏感的代理動作強制執行人工審核關卡，讓代理在行動前能受到監督。

6. 快速入門

如何找到所需內容：瀏覽儲存庫中的模組結構（agentscope-core、agentscope-harness、agentscope-extensions、agentscope-examples），或閱讀 java.agentscope.io 的完整文件。

如何安裝/整合：需要 JDK 17 以上版本。將 harness 模組加入為 Maven 依賴：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
</dependency>

然後建立代理：

HarnessAgent agent = HarnessAgent.builder()
    .name("assistant")
    .model("dashscope:qwen-plus")
    .workspace(Paths.get(".agentscope/workspace"))
    .build();

agent.call(new UserMessage("Hello!"), ctx).block();

如何貢獻：在 github.com/agentscope-ai/agentscope-java 分叉儲存庫，檢閱貢獻指南，然後開啟拉取請求。在較大型貢獻之前，可透過 Discord、釘釘或微信加入社群進行討論。

7. 專案結構

agentscope-java/
├── agentscope-core/               # 核心框架：事件、內容區塊、ReAct 迴圈
├── agentscope-harness/            # 生產控制框架：中介軟體、記憶、計畫模式
├── agentscope-extensions/         # LLM 供應商與管道整合
├── agentscope-service/            # 控制平面與儀表板
├── agentscope-distribution/       # 發行套件封裝
├── agentscope-dependencies-bom/   # 集中式依賴版本管理
├── agentscope-examples/           # 範例實作與快速入門程式碼
└── docs/                          # 文件來源

關鍵目錄：agentscope-core 保存所有代理建構所依賴的基礎抽象；agentscope-harness 是大多數應用程式開發者直接依賴的模組，因為它以生產級中介軟體包覆核心；agentscope-extensions 則是新增 LLM 供應商或管道整合的地方。

8. 相關生態系

上游依賴：LLM 供應商——OpenAI、Anthropic、DashScope（阿里雲）、Google Gemini、DeepSeek 與 Ollama（用於本機模型）。
部署目標：Docker 與 Kubernetes 用於沙箱；Redis、MySQL 與 PostgreSQL 用於狀態持久化；OSS 與 COS（雲端物件儲存）用於分散式復原資料。
互補工具：企業即時通訊平台釘釘、飛書與企業微信，用於基於聊天的代理部署；A2A 與 AG-UI 協定用於與其他代理生態系互通。
兄弟專案：AgentScope（Python），此 Java 實作在概念上與之對齊的原始框架，適用於跨兩種語言生態系協作的團隊。

9. 授權

採用 Apache License 2.0 授權。

✅ 可自由使用、修改與散布，包括用於商業與專有產品。
✅ 允許貢獻者授予專利使用權。
❌ 不提供任何擔保——本軟體按「現況」提供。
ℹ️ 修改過的檔案應保留署名聲明，且散布時必須包含授權條款副本。

10. 常見問題

問：使用 AgentScope Java 需要會 Python 嗎？
答：不需要。AgentScope Java 是原生 JVM 框架（JDK 17 以上），有自己的 Maven 工件——不需要 Python 執行環境或橋接層。

問：開箱即用支援哪些 LLM 供應商？
答：OpenAI、Anthropic、DashScope（阿里雲）、Gemini、DeepSeek 與 Ollama 皆以模組化擴充整合的方式支援。

問：代理可以安全地執行不受信任或高風險的工具呼叫嗎？
答：可以。內建的權限系統讓您可以將個別工具呼叫設為需要人工核准，而工作區/沙箱層可以將執行隔離在 Docker、Kubernetes 或雲端沙箱（AgentRun）中。

問：如果服務實例重新啟動或進行滾動部署，代理狀態會怎樣？
答：工作階段可以持久化到 Redis、MySQL 或 PostgreSQL，讓滾動部署期間可以跨副本復原，不會遺失進行中的工作。

問：如何協調多個代理協同工作？
答：使用 agent_spawn 與 agent_send 原語來建立子代理並在它們之間即時轉發事件。

11. 快速連結

儲存庫：github.com/agentscope-ai/agentscope-java
官方文件：java.agentscope.io
貢獻：請參閱儲存庫中的貢獻指南，了解拉取請求與議題的慣例。
社群：Discord、釘釘與微信頻道，可從儲存庫 README 中連結。

12. 總結

AgentScope Java 將生產級的代理基礎設施——型別化事件、權限關卡、沙箱隔離與分散式工作階段復原——原生帶入 JVM 生態系。它最適合想要建構長時間執行、企業級 AI 代理、且無需採用獨立 Python 技術棧的 Java 與 Spring 團隊，也適合從第一天起就需要人工監督與零停機部署等營運保證的組織。