怎麼設定 AgentScope Java Harness

這篇教你在 Java 專案中建立 AgentScope Java Harness，完成工作區、持久化會話、記憶壓縮與子代理分工。

如果你正在做一個需要保留狀態、隔離工具、並且能在本機或分散式環境運作的 Java 代理，這篇操作指南就是給你看的。照著做完，你會得到一個可執行的 AgentScope Java Harness 專案，包含清楚的工作區結構、可延續的對話紀錄、可控的記憶整理流程，以及後續擴充子代理協作的基礎。

開始之前

• Java 17+
• Maven 3.9+ 或 Gradle 8+
• AgentScope Java 1.1.0+
• 可讀取的官方文件與 GitHub 倉庫：官方文件、GitHub 倉庫
• 你要使用的模型供應商 API key
• 可寫入的本機資料夾，作為工作區根目錄
• 若要測試分散式儲存，請先準備 Redis、OSS 或其他共享後端

Step 1: 建立 Java 專案骨架

這一步的目的，是先做出一個乾淨的 Java 專案，讓 Harness 執行環境與範例程式有地方放。你先把專案建立好，後面才有辦法接入 AgentScope 的元件與設定。

mkdir agentscope-harness-demo
cd agentscope-harness-demo
mvn -q archetype:generate \
  -DgroupId=dev.oracore \
  -DartifactId=agentscope-harness-demo \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

接著把 AgentScope Java 相依性加進你的建置檔，然後執行一次編譯，確認專案能順利解析 Harness 類別。

你應該看到成功建置，沒有缺少套件或無法解析類別的錯誤，這代表專案骨架已經準備好接收後續程式碼。

Step 2: 建立工作區目錄

這一步的目的，是把代理會用到的個人設定、知識、技能、子代理規格與記憶資料統一放進同一個工作區。工作區一旦固定，代理的行為與狀態就比較容易維護，也方便重新啟動後接續使用。

先建立工作區資料夾，並補齊 Harness 會用到的核心檔案與目錄。這裡的重點不是把資料塞滿，而是先把結構定好，讓代理知道要去哪裡讀寫。

mkdir -p .agentscope/workspace/{knowledge,skills,subagents,agents}
touch .agentscope/workspace/AGENTS.md
printf '# 代理規則\n- 回答要簡潔\n- 狀態要保存在工作區\n' > .agentscope/workspace/AGENTS.md

把幾條穩定規則寫進 AGENTS.md，因為這個檔案會成為代理行為的主要依據。之後不管是啟動、重啟，還是切換執行環境，這份規則都能提供一致的上下文。

你應該看到工作區資料夾已經出現在磁碟上，而且 AGENTS.md 內有可讀的指示內容，代表代理在啟動時有明確的起點。

Step 3: 建立 HarnessAgent

這一步的目的，是做出可執行的代理入口，讓它能讀取工作區上下文，並且在多次呼叫之間保留狀態。這是整個 Harness 的核心，因為代理不只是回一次答案，而是要能持續工作。

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model(model)
    .workspace(Paths.get(".agentscope/workspace"))
    .compaction(CompactionConfig.builder()
        .triggerMessages(50)
        .keepMessages(20)
        .build())
    .build();

再把代理和執行時上下文綁在一起，至少要有穩定的 session ID；如果是多人系統，最好再加上 user ID。這樣一來，代理就能把不同使用者或不同對話分開管理。

RuntimeContext ctx = RuntimeContext.builder()
    .sessionId("user-session-001")
    .userId("alice")
    .build();

Msg reply = agent.call(userMessage, ctx).block();

你應該看到第一則回覆正常返回，而且工作區開始出現 session 與記憶相關的產物，代表代理已經真的在使用 Harness，而不是只跑一段靜態程式。

Step 4: 持久化會話與記憶

這一步的目的，是讓代理在重新啟動或收到新請求後，仍然能接回同一段對話。只要會話與記憶能持久化，你就不需要每次都把整段上下文重新餵一次。

請用同一個 sessionId 連續呼叫兩次，然後檢查工作區裡的 session 歷史與 memory 檔案。這一步的驗收重點，是第二次呼叫要能延續第一次的內容。

# 在應用程式以相同 sessionId 跑兩次之後
find .agentscope/workspace -maxdepth 4 | sort

你可以在 agents/.../context/ 找到狀態，在 sessions/ 找到對話紀錄，在 memory/ 找到記憶檔案。這些檔案就是 Harness 幫你保存狀態的具體證據。

你應該看到第二次呼叫會延續前一次的對話，而不是從頭開始，這代表狀態回復已經生效。

Step 5: 切換沙箱或檔案系統後端

這一步的目的，是把儲存與執行層抽象化，讓你可以從本機磁碟切換到共享儲存，或切到沙箱環境，但代理邏輯不用改。這對部署很重要，因為開發、測試、正式環境常常不是同一種儲存方式。

先選擇符合部署型態的檔案系統後端。開發時可以用本機儲存，分散式副本可以用遠端儲存，需要隔離時則改用沙箱儲存。

// 範例：依照環境選擇對應後端
Filesystem fs = FilesystemFactory.local(Paths.get(".agentscope/workspace"));
// 部署時可替換成遠端或沙箱實作

agent = HarnessAgent.builder()
    .filesystem(fs)
    .workspace(Paths.get(".agentscope/workspace"))
    .build();

當你切換後端時，代理程式碼應該維持不變，而檔案讀寫與工具執行則改由新的儲存層處理。這樣做可以把風險集中在基礎設施，不會影響上層邏輯。

你應該能從筆電執行切換到共享後端，仍然讀到同一份工作區檔案，這就表示抽象層有成功生效。

Step 6: 拆分成子代理

這一步的目的，是讓主代理把長任務或平行任務交給子代理處理，避免主代理變成一個難以維護的大單體。當任務變多時，這種拆分會讓架構更清楚。

你可以在程式內或 workspace/subagents/ 裡定義子代理，然後依任務性質選擇同步或非同步呼叫。同步適合需要立即回傳的工作，非同步適合長時間處理的工作。

// 子代理委派範例
SubAgentSpec spec = SubAgentSpec.builder()
    .name("researcher")
    .description("負責研究與摘要")
    .build();

agent = HarnessAgent.builder()
    .subagent(spec)
    .build();

你應該看到子代理出現在工作區或執行時註冊表中，而且被委派的工作會以受控方式回傳給主代理。這代表你的代理已經具備基本的分工能力。

常見錯誤

• 每次請求都換新的 sessionId。修法：同一段對話請固定使用同一個 sessionId，這樣 Harness 才能恢復狀態。
• 跳過工作區結構。修法：第一次執行前先建立 AGENTS.md、memory/、knowledge/、skills/ 與 subagents/。
• 把不受信任的命令直接丟到主機執行。修法：啟用沙箱執行，或改用能隔離工具的後端。

接下來可以看什麼

當基本 Harness 跑通之後，你可以再往前做自訂記憶彙整、分散式檔案系統適配器，以及更完整的子代理工作流，例如資料分析、SRE 自動化或程式助理。這些進階主題會把目前的雛形，推進成真正可上線的代理系統。