在 Conductor 中运行 LangGraph4j Agent:Java 框架 Agent 的持久化执行指南
在 Conductor 中运行 LangGraph4j Agent:Java 框架 Agent 的持久化执行指南
本指南讲解如何将使用 LangGraph4j(结合 LangChain4j 的 OpenAI 模型)构建的 Java Agent,通过 conductor-ai Java SDK 桥接到 Conductor 的事件驱动持久化执行引擎中运行。你将学会引入依赖、用 AgentExecutor 组装 Agent、通过 AgentRuntime 启动一次可观测的持久化执行,以及理解从框架对象到可复用 AGENT 任务的完整链路。
LangGraph4j Agent 与 Conductor 的桥接方式
Conductor 是一个事件驱动的 Agentic 工作流引擎,为应用程序和 AI Agent 提供持久化、高弹性的执行能力。对于已经用其他框架编写好的 Agent(如 OpenAI Agents、LangChain、LangGraph、Google ADK),Conductor 的定位是:你保留框架定义好的 Agent 对象,由 Conductor SDK 将其编译并作为一次可持久化、可观测的 Conductor 执行来运行(参见 Bring Your Framework Agent)。
LangGraph4j 是 LangGraph 的 Java 移植,其 AgentExecutor 是官方的 Agent 执行器,配合 LangChain4j 的 ChatModel 使用。conductor-ai(org.conductoross:conductor-ai)则是 Conductor 的 Java Agent SDK,负责把 LangGraph4j 的 Agent 对象接入 Conductor 运行时。文档 LangGraph4j bridge documentation 对应的就是这条桥接路径的最小可用示例。
1. 添加依赖
在 Gradle 项目的 build.gradle 中引入以下三个依赖:
implementation 'org.conductoross:conductor-ai'
compileOnly 'dev.langchain4j:langchain4j-open-ai:1.0.0'
compileOnly 'org.bsc.langgraph4j:langgraph4j-agent-executor:1.6.0-beta5'
逐条说明:
org.conductoross:conductor-ai:Conductor 的 Java Agent SDK,提供AgentRuntime等运行时类,是桥接的核心依赖(implementation作用域,编译与运行期都需要)。dev.langchain4j:langchain4j-open-ai:1.0.0:LangChain4j 的 OpenAI 模型实现,提供OpenAiChatModel。使用compileOnly意味着它仅在编译期可见,运行期由你的运行时环境提供。org.bsc.langgraph4j:langgraph4j-agent-executor:1.6.0-beta5:LangGraph4j 的 AgentExecutor 模块,提供org.bsc.langgraph4j.agentexecutor.AgentExecutor类。
注意
compileOnly的语义:如果你的项目运行时确实需要这些类(例如在本地直接运行本指南的示例),请确认它们在运行 classpath 上;compileOnly适合 SDK 被打包为库、由最终应用自行提供依赖的场景。
2. 用 Builder 组装并运行 LangGraph4j Agent
以下是完整的运行代码,分为"构建 ChatModel → 构建 AgentExecutor → 通过 AgentRuntime 运行"三步:
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import org.bsc.langgraph4j.agentexecutor.AgentExecutor;
import org.conductoross.conductor.ai.AgentRuntime;
ChatModel model = OpenAiChatModel.builder()
.apiKey("conductor-server-handles-credentials")
.modelName("gpt-4o-mini")
.build();
AgentExecutor.Builder agent = AgentExecutor.builder().chatModel(model);
try (AgentRuntime runtime = new AgentRuntime()) {
runtime.run(agent, "Share a state-machine fact.").printResult();
}
关键点拆解:
- 模型构建:使用 LangChain4j 的
OpenAiChatModel.builder(),modelName("gpt-4o-mini")指定模型。apiKey传入占位符字符串"conductor-server-handles-credentials"——这是刻意为之:凭据不由客户端 SDK 直接管理,而是由 Conductor 服务器统一处理。也就是说,客户端代码中无需写入真实密钥,模型调用发生时由服务器侧完成鉴权。 - Agent 组装:
AgentExecutor.builder().chatModel(model)将 ChatModel 注入 LangGraph4j 的 AgentExecutor。AgentExecutor 是 LangGraph 风格的 Agent 执行器,内部维护状态图(StateGraph),负责 LLM 推理与工具调用循环。 - 持久化运行:
AgentRuntime实现了AutoCloseable,因此使用 try-with-resources。runtime.run(agent, "...")将传入的 Agent 对象编译为一次 Conductor 执行并运行,返回的结果对象调用printResult()打印输出。
从第一次运行起,这次执行就是一次持久化执行:每个 LLM 调用、工具调用、等待、重试与分支都会以工作流任务的形式记录在 Conductor 服务器上,可在 Conductor UI 中查看(框架对象到工作流步骤的转换路径见 agent-framework-recipes.md 中的流程示意图)。
3. 配置服务器地址与凭据
运行前需要配置 Conductor 服务器地址。在 shell 中导出环境变量:
export CONDUCTOR_SERVER_URL={{CONDUCTOR_SERVER_URL}}
# For authenticated Conductor servers:
# export CONDUCTOR_AUTH_KEY=<YOUR_AUTH_KEY>
# export CONDUCTOR_AUTH_SECRET=<YOUR_AUTH_SECRET>
| 环境变量 | 是否必填 | 说明 |
|---|---|---|
CONDUCTOR_SERVER_URL |
必填 | Conductor 服务器地址。{{CONDUCTOR_SERVER_URL}} 是占位符,请替换为实际的服务器 URL(如本地开发版或已部署实例的地址) |
CONDUCTOR_AUTH_KEY |
认证服务器必填 | Conductor 的认证密钥(Access Key),在开启认证的服务器上提供 |
CONDUCTOR_AUTH_SECRET |
认证服务器必填 | 与 CONDUCTOR_AUTH_KEY 配对的密钥(Secret),用于签名请求 |
在开始服务器前,还需确保 Conductor 服务器能够访问你的模型提供商:在 Developer Edition 上,将提供商添加为 AI/LLM 集成;在本地服务器上,则在启动前导出提供商的 API Key(参见 framework-agents.md)。这与代码中 "conductor-server-handles-credentials" 占位符的设计一致——真实凭据在服务器侧配置。
4. 验证执行结果
运行包含上述代码的 Java 类后,printResult() 会在控制台打印 Agent 的最终输出(例如一条状态机相关的知识性回答)。建议同时完成以下验证:
- 检查控制台输出:确认 Agent 正常完成推理并返回结果;
- 在 Conductor UI 中定位对应执行:找到刚运行产生的执行实例,检查其任务列表——LangGraph4j Agent 的整个运行过程已被拆解为可见的任务;
- 失败排查顺序:若执行失败,按 framework-agents.md 的建议,依次检查运行时服务器 URL、框架包版本、模型提供商凭据,然后查看失败任务的具体错误再重试。
5. 从开发运行到生产部署:run / plan / deploy / serve
runtime.run(...) 适合开发期迭代。当你希望将 LangGraph4j Agent 作为可复用、带版本的 Conductor Agent 提供给工作流调用时,走完整的生命周期(详见 conductor-agents.md):
- Create:在代码中定义 Agent(本指南中的
AgentExecutor.Builder对象即框架定义); - Plan:检查 Agent 将被编译成的工作流图,适合开发与 CI 阶段,在部署前验证;
- Deploy:将编译后的 Agent 注册到服务器,成为命名的、带版本的 Conductor Agent;
- Serve:启动执行 Agent 工具函数的 worker 进程(框架的工具作为本地函数运行时,需要常驻进程执行它们);
- Run:开发期
run一步完成编译与执行;生产期由工作流通过AGENT任务按名称调用已部署版本。
在 Python SDK 中这四步是同一个 runtime 上的四个调用(agent-framework-recipes.md):
with AgentRuntime() as runtime:
runtime.run(agent, "Is the token set?") # develop: compile and execute once
runtime.plan(agent) # CI: inspect the compiled graph
runtime.deploy(agent) # release: register without executing
runtime.serve(agent) # operate: run tool workers and block
serve() 会阻塞,因此生产环境中它应运行在独立的长生命周期 worker 进程中,而 deploy() 在 CI/CD 中执行。
6. 在工作流中调用已部署的 Agent
一旦部署完成,父工作流即可通过 AGENT 任务按名称调用该 Agent,调用方式与调用任何其他持久化任务一致:
{
"name": "run_agent",
"taskReferenceName": "run_agent_ref",
"type": "AGENT",
"inputParameters": {
"agentType": "conductor",
"name": "<deployed-agent-name>",
"prompt": "${workflow.input.prompt}"
}
}
(示例见 agent-framework-recipes.md)
需要澄清一个关键概念:agentType 选择的是执行模式,而非编写框架(conductor-agents.md):
agentType: "a2a"(默认)调用远程 A2A 端点;agentType: "conductor"按name运行已部署的 Conductor Agent。
OpenAI Agents、Google ADK、LangGraph4j 等框架是 SDK 的编写路径,它们本身不是 agentType 的值。LangGraph4j 编写的 Agent 经过 SDK 编译部署后,同样以 agentType: "conductor" 被工作流调用。
7. 服务器端前置:开启 AI 集成
部署或调用 Conductor Agent 之前,需要在服务器配置中开启 AI 集成:
conductor.integrations.ai.enabled=true
当该属性为 false 或缺失时,已部署 Agent 的控制面以及 agentType: "conductor" 执行模式均不可用(参见 conductor-agents.md)。
8. 凭据与提供商:服务器侧处理的背后实现
本指南代码中 .apiKey("conductor-server-handles-credentials") 的占位符用法,与仓库中 ai 模块的提供商体系相印证。ai/src/main/java/org/conductoross/conductor/ai/providers/openai/OpenAIConfiguration.java 等配置文件定义了各提供商的服务器侧配置入口;ai 模块下还有 providers/anthropic、providers/gemini、providers/bedrock、providers/ollama 等多个提供商实现,以及 AIModelProvider.java、LLMs.java 等统一接入点(见 ai 模块源码)。这意味着 LangGraph4j Agent 的 LLM 调用最终由服务器侧按提供商配置完成,客户端只负责描述 Agent 逻辑与执行请求。
9. 排查与最佳实践
- 依赖版本:
langchain4j-open-ai:1.0.0与langgraph4j-agent-executor:1.6.0-beta5是文档锁定的编译版本,升级 LangGraph4j 时注意与AgentExecutor.BuilderAPI 的兼容性; - 环境变量未生效:确认
CONDUCTOR_SERVER_URL已导出到运行 Java 进程的 shell 环境中,认证服务器还需同时导出CONDUCTOR_AUTH_KEY与CONDUCTOR_AUTH_SECRET; AgentRuntime资源释放:始终使用 try-with-resources 包裹,确保底层连接被正确关闭;- 服务端凭据:不要在客户端代码中硬编码模型 API Key,遵循占位符 + 服务器侧配置的模式;
- 幂等与重试:Agent 动作若产生外部副作用,重试前先确认其幂等性与恢复策略(参见 framework-agents.md);
- 生产架构:部署后保持 worker 进程常驻(
serve),并在 CI/CD 中执行deploy;更完整的生产化路径可参考 production-agent-architecture。
更多资源
- LangGraph 框架 Agent 快速入门:Python 版 LangGraph Agent(
create_react_agent)通过 Conductor 运行的对应示例,可作为对照理解桥接模式; - Framework Agents 参考:各框架支持矩阵、框架对象到工作流步骤的完整转换流程与维护中的 SDK 示例索引;
- Conductor Agents:已部署 Agent 的调用、等待、恢复、取消与输出语义;
- Java 其他框架指南:不使用外部框架、直接用
Agent.builder()编写原生 Conductor Agent 的对照路径。