[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"article-how-to-set-up-agentscope-java-harness-zh":3,"article-related-how-to-set-up-agentscope-java-harness-zh":31,"series-ai-agent-823f413f-0504-425c-a8de-956a60754b9d":82},{"id":4,"slug":5,"title":6,"content":7,"summary":8,"source":9,"source_url":10,"author":11,"image_url":12,"cover_image":12,"category":13,"language":14,"translated_content":11,"related_article_id":15,"keywords":16,"key_takeaways":23,"views":27,"created_at":28,"published_at":29,"topic_cluster_id":30},"823f413f-0504-425c-a8de-956a60754b9d","how-to-set-up-agentscope-java-harness-zh","怎麼設定 AgentScope Java Harness","\u003Cp data-speakable=\"summary\">這篇教你在 Java 專案中建立 AgentScope Java Harness，完成工作區、持久化會話、記憶壓縮與子代理分工。\u003C\u002Fp>\u003Cp>如果你正在做一個需要保留狀態、隔離工具、並且能在本機或分散式環境運作的 Java 代理，這篇操作指南就是給你看的。照著做完，你會得到一個可執行的 AgentScope Java Harness 專案，包含清楚的工作區結構、可延續的對話紀錄、可控的記憶整理流程，以及後續擴充子代理協作的基礎。\u003C\u002Fp>\u003Ch2>開始之前\u003C\u002Fh2>\u003Cul>\u003Cli>Java 17+\u003C\u002Fli>\u003Cli>Maven 3.9+ 或 Gradle 8+\u003C\u002Fli>\u003Cli>AgentScope Java 1.1.0+\u003C\u002Fli>\u003Cli>可讀取的官方文件與 GitHub 倉庫：\u003Ca href=\"https:\u002F\u002Fagentscope.io\u002Fdocs\">官方文件\u003C\u002Fa>、\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002Fagentscope-java\">GitHub 倉庫\u003C\u002Fa>\u003C\u002Fli>\u003Cli>你要使用的模型供應商 API key\u003C\u002Fli>\u003Cli>可寫入的本機資料夾，作為工作區根目錄\u003C\u002Fli>\u003Cli>若要測試分散式儲存，請先準備 Redis、OSS 或其他共享後端\u003C\u002Fli>\u003C\u002Ful>\u003Ch2>Step 1: 建立 Java 專案骨架\u003C\u002Fh2>\u003Cp>這一步的目的，是先做出一個乾淨的 Java 專案，讓 Harness 執行環境與範例程式有地方放。你先把專案建立好，後面才有辦法接入 AgentScope 的元件與設定。\u003C\u002Fp>\n\u003Cfigure class=\"my-6\">\u003Cimg src=\"https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780877895461-376p.png\" alt=\"怎麼設定 AgentScope Java Harness\" class=\"rounded-xl w-full\" loading=\"lazy\" \u002F>\u003C\u002Ffigure>\n\u003Cpre>\u003Ccode>mkdir agentscope-harness-demo\ncd agentscope-harness-demo\nmvn -q archetype:generate \\\n  -DgroupId=dev.oracore \\\n  -DartifactId=agentscope-harness-demo \\\n  -DarchetypeArtifactId=maven-archetype-quickstart \\\n  -DinteractiveMode=false\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>接著把 AgentScope Java 相依性加進你的建置檔，然後執行一次編譯，確認專案能順利\u003Ca href=\"\u002Fnews\u002Fdefi-development-dfdv-stock-price-analysis-zh\">解析\u003C\u002Fa> Harness 類別。\u003C\u002Fp>\u003Cp>你\u003Ca href=\"\u002Fnews\u002Fwhy-openclaw-lakehouse-should-meet-in-chat-zh\">應該\u003C\u002Fa>看到成功建置，沒有缺少套件或無法解析類別的錯誤，這代表專案骨架已經準備好接收後續程式碼。\u003C\u002Fp>\u003Ch2>Step 2: 建立工作區目錄\u003C\u002Fh2>\u003Cp>這一步的目的，是把代理會用到的個人設定、知識、技能、子代理規格與記憶資料統一放進同一個工作區。工作區一旦固定，代理的行為與狀態就比較容易維護，也方便重新啟動後接續使用。\u003C\u002Fp>\n\u003Cfigure class=\"my-6\">\u003Cimg src=\"https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780877898112-x0bj.png\" alt=\"怎麼設定 AgentScope Java Harness\" class=\"rounded-xl w-full\" loading=\"lazy\" \u002F>\u003C\u002Ffigure>\n\u003Cp>先建立工作區資料夾，並補齊 Harness 會用到的核心檔案與目錄。這裡的重點不是把資料塞滿，而是先把結構定好，讓代理知道要去哪裡讀寫。\u003C\u002Fp>\u003Cpre>\u003Ccode>mkdir -p .agentscope\u002Fworkspace\u002F{knowledge,skills,subagents,agents}\ntouch .agentscope\u002Fworkspace\u002FAGENTS.md\nprintf '# 代理規則\\n- 回答要簡潔\\n- 狀態要保存在工作區\\n' > .agentscope\u002Fworkspace\u002FAGENTS.md\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>把幾條穩定規則寫進 \u003Ccode>AGENTS.md\u003C\u002Fcode>，因為這個檔案會成為代理行為的主要依據。之後不管是啟動、重啟，還是切換執行環境，這份規則都能提供一致的上下文。\u003C\u002Fp>\u003Cp>你應該看到工作區資料夾已經出現在磁碟上，而且 \u003Ccode>AGENTS.md\u003C\u002Fcode> 內有可讀的指示內容，代表代理在啟動時有明確的起點。\u003C\u002Fp>\u003Ch2>Step 3: 建立 HarnessAgent\u003C\u002Fh2>\u003Cp>這一步的目的，是做出可執行的代理入口，讓它能讀取工作區上下文，並且在多次呼叫之間保留狀態。這是整個 Harness 的核心，因為代理不只是回一次答案，而是要能持續工作。\u003C\u002Fp>\u003Cpre>\u003Ccode>HarnessAgent agent = HarnessAgent.builder()\n    .name(\"my-agent\")\n    .model(model)\n    .workspace(Paths.get(\".agentscope\u002Fworkspace\"))\n    .compaction(CompactionConfig.builder()\n        .triggerMessages(50)\n        .keepMessages(20)\n        .build())\n    .build();\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>再把代理和執行時上下文綁在一起，至少要有穩定的 session ID；如果是多人系統，最好再加上 user ID。這樣一來，代理就能把不同使用者或不同對話分開管理。\u003C\u002Fp>\u003Cpre>\u003Ccode>RuntimeContext ctx = RuntimeContext.builder()\n    .sessionId(\"user-session-001\")\n    .userId(\"alice\")\n    .build();\n\nMsg reply = agent.call(userMessage, ctx).block();\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>你應該看到第一則回覆正常返回，而且工作區開始出現 session 與記憶相關的產物，代表代理已經真的在使用 Harness，而不是只跑一段靜態程式。\u003C\u002Fp>\u003Ch2>Step 4: 持久化會話與記憶\u003C\u002Fh2>\u003Cp>這一步的目的，是讓代理在重新啟動或收到新請求後，仍然能接回同一段對話。只要會話與記憶能持久化，你就不需要每次都把整段上下文重新餵一次。\u003C\u002Fp>\u003Cp>請用同一個 \u003Ccode>sessionId\u003C\u002Fcode> 連續呼叫兩次，然後檢查工作區裡的 session 歷史與 memory 檔案。這一步的驗收重點，是第二次呼叫要能延續第一次的內容。\u003C\u002Fp>\u003Cpre>\u003Ccode># 在應用程式以相同 sessionId 跑兩次之後\nfind .agentscope\u002Fworkspace -maxdepth 4 | sort\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>你可以在 \u003Ccode>agents\u002F...\u002Fcontext\u002F\u003C\u002Fcode> 找到狀態，在 \u003Ccode>sessions\u002F\u003C\u002Fcode> 找到對話紀錄，在 \u003Ccode>memory\u002F\u003C\u002Fcode> 找到記憶檔案。這些檔案就是 Harness 幫你保存狀態的具體證據。\u003C\u002Fp>\u003Cp>你應該看到第二次呼叫會延續前一次的對話，而不是從頭開始，這代表狀態回復已經生效。\u003C\u002Fp>\u003Ch2>Step 5: 切換沙箱或檔案系統後端\u003C\u002Fh2>\u003Cp>這一步的目的，是把儲存與執行層抽象化，讓你可以從本機磁碟切換到共享儲存，或切到沙箱環境，但代理邏輯不用改。這對部署很重要，因為開發、測試、正式環境常常不是同一種儲存方式。\u003C\u002Fp>\u003Cp>先選擇符合部署型態的檔案系統後端。開發時可以用本機儲存，分散式副本可以用遠端儲存，需要隔離時則改用沙箱儲存。\u003C\u002Fp>\u003Cpre>\u003Ccode>\u002F\u002F 範例：依照環境選擇對應後端\nFilesystem fs = FilesystemFactory.local(Paths.get(\".agentscope\u002Fworkspace\"));\n\u002F\u002F 部署時可替換成遠端或沙箱實作\n\nagent = HarnessAgent.builder()\n    .filesystem(fs)\n    .workspace(Paths.get(\".agentscope\u002Fworkspace\"))\n    .build();\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>當你切換後端時，代理程式碼應該維持不變，而檔案讀寫與工具執行則改由新的儲存層處理。這樣做可以把風險集中在基礎設施，不會影響上層邏輯。\u003C\u002Fp>\u003Cp>你應該能從筆電執行切換到共享後端，仍然讀到同一份工作區檔案，這就表示抽象層有成功生效。\u003C\u002Fp>\u003Ch2>Step 6: 拆分成子代理\u003C\u002Fh2>\u003Cp>這一步的目的，是讓主代理把長任務或平行任務交給子代理處理，避免主代理變成一個難以維護的大單體。當任務變多時，這種拆分會讓架構更清楚。\u003C\u002Fp>\u003Cp>你可以在程式內或 \u003Ccode>workspace\u002Fsubagents\u002F\u003C\u002Fcode> 裡定義子代理，然後依任務性質選擇同步或非同步呼叫。同步\u003Ca href=\"\u002Fnews\u002F5-reasons-openrag-fits-rag-teams-zh\">適合\u003C\u002Fa>需要立即回傳的工作，非同步適合長時間處理的工作。\u003C\u002Fp>\u003Cpre>\u003Ccode>\u002F\u002F 子代理委派範例\nSubAgentSpec spec = SubAgentSpec.builder()\n    .name(\"researcher\")\n    .description(\"負責研究與摘要\")\n    .build();\n\nagent = HarnessAgent.builder()\n    .subagent(spec)\n    .build();\u003C\u002Fcode>\u003C\u002Fpre>\u003Cp>你應該看到子代理出現在工作區或執行時註冊表中，而且被委派的工作會以受控方式回傳給主代理。這代表你的代理已經具備基本的分工能力。\u003C\u002Fp>\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>指標\u003C\u002Fth>\u003Cth>基準／優化前\u003C\u002Fth>\u003Cth>結果／優化後\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>上下文處理\u003C\u002Ftd>\u003Ctd>單一且持續膨脹的提示詞\u003C\u002Ftd>\u003Ctd>壓縮後仍保留最近訊息\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>狀態保存\u003C\u002Ftd>\u003Ctd>重新啟動後遺失\u003C\u002Ftd>\u003Ctd>可從工作區會話檔回復\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>執行安全\u003C\u002Ftd>\u003Ctd>工具直接在主程序執行\u003C\u002Ftd>\u003Ctd>工具可改在隔離沙箱執行\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>部署彈性\u003C\u002Ftd>\u003Ctd>只能使用本機目錄\u003C\u002Ftd>\u003Ctd>可切換本機、遠端或沙箱後端\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003Ch2>常見錯誤\u003C\u002Fh2>\u003Cul>\u003Cli>每次請求都換新的 \u003Ccode>sessionId\u003C\u002Fcode>。修法：同一段對話請固定使用同一個 \u003Ccode>sessionId\u003C\u002Fcode>，這樣 Harness 才能恢復狀態。\u003C\u002Fli>\u003Cli>跳過工作區結構。修法：第一次執行前先建立 \u003Ccode>AGENTS.md\u003C\u002Fcode>、\u003Ccode>memory\u002F\u003C\u002Fcode>、\u003Ccode>knowledge\u002F\u003C\u002Fcode>、\u003Ccode>skills\u002F\u003C\u002Fcode> 與 \u003Ccode>subagents\u002F\u003C\u002Fcode>。\u003C\u002Fli>\u003Cli>把不受信任的命令直接丟到主機執行。修法：啟用沙箱執行，或改用能隔離工具的後端。\u003C\u002Fli>\u003C\u002Ful>\u003Ch2>接下來可以看什麼\u003C\u002Fh2>\u003Cp>當基本 Harness 跑通之後，你可以再往前做自訂記憶彙整、分散式檔案系統適配器，以及更完整的子代理工作流，例如資料分析、SRE 自動化或程式助理。這些進階主題會把目前的雛形，推進成真正可上線的代理系統。\u003C\u002Fp>","這篇教你在 Java 專案中建立 AgentScope Java Harness，完成工作區、持久化會話、記憶壓縮與子代理分工。","zhuanlan.zhihu.com","https:\u002F\u002Fzhuanlan.zhihu.com\u002Fp\u002F2043265948854047649",null,"https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780877895461-376p.png","ai-agent","zh","3277d511-db37-4457-845d-dc0cacb94585",[17,18,19,20,21,22],"AgentScope Java","Harness","Java 17","工作區","記憶壓縮","子代理",[24,25,26],"先建立固定的工作區結構，再讓 Harness 讀取與寫入狀態。","使用穩定的 sessionId，才能讓會話與記憶在重啟後延續。","把檔案系統與工具執行抽象化，後續才能安全切換到沙箱或共享後端。",0,"2026-06-08T00:17:46.417304+00:00","2026-06-08T00:17:46.395+00:00","e3b68196-9e64-4c18-a3b6-a73e73bfb367",{"tags":32,"relatedLang":41,"relatedPosts":45},[33,34,36,38,40],{"name":21,"slug":21},{"name":17,"slug":35},"agentscope-java",{"name":37,"slug":37},"harness",{"name":19,"slug":39},"java-17",{"name":20,"slug":20},{"id":15,"slug":42,"title":43,"language":44},"how-to-set-up-agentscope-java-harness-en","How to Set Up AgentScope Java Harness","en",[46,52,58,64,70,76],{"id":47,"slug":48,"title":49,"cover_image":50,"image_url":50,"created_at":51,"category":13},"066e5903-7569-402f-a397-f01468ffecd4","reid-hoffman-leaves-microsoft-board-manus-ai-zh","霍夫曼離開微軟董事會，轉向 Manus","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780827469679-fpyr.png","2026-06-07T10:17:21.250923+00:00",{"id":53,"slug":54,"title":55,"cover_image":56,"image_url":56,"created_at":57,"category":13},"fb5eb422-6013-43fe-bdc4-26c57eee0d9e","how-to-understand-codex-chatgpt-merge-zh","怎麼理解 Codex 與 ChatGPT 合併","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780704172974-ypaa.png","2026-06-06T00:02:25.891496+00:00",{"id":59,"slug":60,"title":61,"cover_image":62,"image_url":62,"created_at":63,"category":13},"83c2f8f6-3710-466e-b52c-473b811f0535","how-to-set-up-openclaw-safely-zh","如何安全架設 OpenClaw","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780549368665-1t2l.png","2026-06-04T05:02:21.26625+00:00",{"id":65,"slug":66,"title":67,"cover_image":68,"image_url":68,"created_at":69,"category":13},"0ba5b1a8-82c5-464a-bea5-9a2c8730da74","aws-devops-agent-turns-incident-chaos-into-triage-zh","AWS DevOps Agent 把事故排查變成三步","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780466689960-g1sv.png","2026-06-03T06:03:14.154923+00:00",{"id":71,"slug":72,"title":73,"cover_image":74,"image_url":74,"created_at":75,"category":13},"841eac88-b0f0-4a4c-9e1e-efc3b5c16281","kimi-k26-live-300-agent-workflows-zh","Kimi K2.6 上線：300 代理工作流","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780430574285-hqpn.png","2026-06-02T20:02:24.972179+00:00",{"id":77,"slug":78,"title":79,"cover_image":80,"image_url":80,"created_at":81,"category":13},"f0411957-bcdb-42d9-a267-3e90ae7d9cb1","how-to-take-a-sabbatical-at-openai-zh","怎麼申請 OpenAI sabbatical","https:\u002F\u002Fxxdpdyhzhpamafnrdkyq.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fcovers\u002Finline-1780398216422-8fi7.png","2026-06-02T11:02:25.74372+00:00",[83,88,93,98,103,108,113,118,123,128],{"id":84,"slug":85,"title":86,"created_at":87},"4ae1e197-1d3d-4233-8733-eafe9cb6438b","claude-now-uses-your-pc-to-finish-tasks-zh","Claude 開始幫你操作電腦","2026-03-26T07:20:48.457387+00:00",{"id":89,"slug":90,"title":91,"created_at":92},"5bede67f-e21c-413d-9ab8-54a3c3d26227","googles-2026-ai-agent-report-decoded-zh","Google 2026 AI Agent 報告解讀","2026-03-26T11:15:22.651956+00:00",{"id":94,"slug":95,"title":96,"created_at":97},"2987d097-563f-46c7-b76f-b558d8ef7c2b","kimi-k25-review-stronger-still-not-legend-zh","Kimi K2.5 評測：更強，但還不是神作","2026-03-27T07:15:55.277513+00:00",{"id":99,"slug":100,"title":101,"created_at":102},"95c9053b-e3f4-4cb5-aace-5c54f4c9e044","claude-code-controls-mac-desktop-zh","Claude Code 也能操控 Mac 了","2026-03-28T03:01:58.58121+00:00",{"id":104,"slug":105,"title":106,"created_at":107},"dc58e153-e3a8-4c06-9b96-1aa64eabbf5f","cloudflare-100x-faster-ai-agent-sandbox-zh","Cloudflare 的 AI 沙箱跑超快","2026-03-28T03:09:44.142236+00:00",{"id":109,"slug":110,"title":111,"created_at":112},"1c8afc56-253f-47a2-979f-1065ff072f2a","openai-backs-isara-agent-swarm-bet-zh","OpenAI 挺 Isara 的 agent swarm …","2026-03-28T03:15:27.513155+00:00",{"id":114,"slug":115,"title":116,"created_at":117},"7379b422-576e-45df-ad5a-d57a0d9dd467","openai-plan-automated-ai-researcher-zh","OpenAI 想做自動化 AI 研究員","2026-03-28T03:17:42.090548+00:00",{"id":119,"slug":120,"title":121,"created_at":122},"48c9889e-86df-450b-a356-e4a4b7c83c5b","harness-engineering-ai-agent-reliability-2026-zh","駕馭工程：從「馬具」到「作業系統」，AI Agent 可靠性的終極密碼","2026-03-31T06:42:53.556721+00:00",{"id":124,"slug":125,"title":126,"created_at":127},"96d8e8c8-1edd-475d-9145-b1e7a1b02b65","mcp-explained-from-prompts-to-production-zh","MCP 怎麼把提示詞變工作流","2026-04-01T09:24:39.321274+00:00",{"id":129,"slug":130,"title":131,"created_at":132},"f2ca7720-b471-4ce5-9336-2a9ac2a876fd","amazon-bedrock-agents-multi-agent-workflows-zh","Amazon Bedrock Agents 進入多代理工作流","2026-04-01T09:30:29.945429+00:00"]