在 Conductor 中运行 LangGraph4j Agent:Java 框架 Agent 的持久化执行指南

原创2026-09-09 19:07:392,232 阅读
文章标签:后端工作流自动化流程编排微服务任务调度人工智能大模型AI AgentAgent 工作流工具调用前端消息队列

在 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 的最终输出(例如一条状态机相关的知识性回答)。建议同时完成以下验证:

  1. 检查控制台输出:确认 Agent 正常完成推理并返回结果;
  2. 在 Conductor UI 中定位对应执行:找到刚运行产生的执行实例,检查其任务列表——LangGraph4j Agent 的整个运行过程已被拆解为可见的任务;
  3. 失败排查顺序:若执行失败,按 framework-agents.md 的建议,依次检查运行时服务器 URL、框架包版本、模型提供商凭据,然后查看失败任务的具体错误再重试。

5. 从开发运行到生产部署:run / plan / deploy / serve

runtime.run(...) 适合开发期迭代。当你希望将 LangGraph4j Agent 作为可复用、带版本的 Conductor Agent 提供给工作流调用时,走完整的生命周期(详见 conductor-agents.md):

  1. Create:在代码中定义 Agent(本指南中的 AgentExecutor.Builder 对象即框架定义);
  2. Plan:检查 Agent 将被编译成的工作流图,适合开发与 CI 阶段,在部署前验证;
  3. Deploy:将编译后的 Agent 注册到服务器,成为命名的、带版本的 Conductor Agent;
  4. Serve:启动执行 Agent 工具函数的 worker 进程(框架的工具作为本地函数运行时,需要常驻进程执行它们);
  5. 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.Builder API 的兼容性;
  • 环境变量未生效:确认 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 的对照路径。
登录后查看全文
conductor