企业官网建设流程全解析

Conductor Java 原生 Agent 快速上手：用 AgentRuntime 运行你的第一个可持久化 AI Agent

【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor

导读

本文讲解如何基于 Conductor 的 Java SDK 原生能力（org.conductoross:conductor-ai），通过Agent构建器与AgentRuntime在数分钟内定义并运行第一个 AI Agent。读完本文，你将掌握 SDK 依赖引入、环境变量配置、Agent 定义与运行、执行结果验证，以及理解"Agent 被编译为工作流图、每次 LLM 调用与工具调用都是可持久化任务"这一核心运行模型，并学会如何将已部署的 Agent 以AGENT任务的形式接入业务工作流。

1. 前置准备：连接 Conductor 并启用 AI 集成

在编写 Java 代码之前，需要先确认两件事：SDK 能够连到哪个 Conductor 服务器，以及服务器是否已启用 AI 集成。

• 服务器连接：完成仓库中的 Connect to Conductor 步骤，得到CONDUCTOR_SERVER_URL（以及认证场景下的CONDUCTOR_AUTH_KEY/CONDUCTOR_AUTH_SECRET）。
• 启用 AI 集成：部署或调用 Conductor Agent 前，需在服务器配置中显式开启 AI 集成：

conductor.integrations.ai.enabled=true

该属性未开启或缺省时，已部署 Agent 的控制平面以及agentType: "conductor"执行模式均不可用（详见 conductor-agents.md）。

• 模型凭据位置：模型提供方的 API Key 等凭据应存放在 Agent 工作进程的环境变量或密钥系统中，不要写入 workflow input。

2. 添加 SDK 依赖

在 Gradle 项目的build.gradle中添加conductor-ai依赖：

dependencies { implementation 'org.conductoross:conductor-ai' }

Maven 用户可参考仓库 first-agent.md 中给出的等价坐标（org.conductoross:conductor-client-ai，版本号按发布版本填写）：

<dependency> <groupId>org.conductoross</groupId> <artifactId>conductor-client-ai</artifactId> <version>VERSION</version> </dependency>

从当前仓库的源码结构看，AI 能力集中在ai模块中（ai/src/main/java/org/conductoross/conductor/ai），其中：

• providers/目录下按提供方组织模型适配器，包括openai、anthropic、gemini、bedrock、ollama、mistral、cohere等，这正是环境变量中模型名（如openai/gpt-4o-mini）的提供方来源；
• tasks/mapper/与tasks/worker/目录将 LLM 调用、MCP 工具调用、Agent 调用等映射为可执行的任务类型；
• agent/目录提供ConductorAgentClient、ConductorAgentDelegate等运行时客户端，负责与服务器上的 Agent 执行环境交互。

3. 配置环境变量

运行 Agent 前，在进程环境中设置以下变量：

export CONDUCTOR_SERVER_URL={{CONDUCTOR_SERVER_URL}} # 认证服务器（Conductor 需要鉴权时）： # export CONDUCTOR_AUTH_KEY=<YOUR_AUTH_KEY> # export CONDUCTOR_AUTH_SECRET=<YOUR_AUTH_SECRET> export CONDUCTOR_AGENT_LLM_MODEL=openai/gpt-4o-mini

注意：模型名中的前缀必须能被 SDK 的模型提供方解析（对应上文ai/src/main/java/.../ai/providers下的各提供方实现），否则运行时会因无法路由到正确的模型端点而失败。

4. 定义并运行你的第一个 Java Agent

以下代码来自 native.md 的完整示例，演示了Agent构建器 +AgentRuntime的最小可用形态：

import org.conductoross.conductor.ai.Agent; import org.conductoross.conductor.ai.AgentRuntime; import org.conductoross.conductor.ai.model.AgentResult; Agent agent = Agent.builder() .name("java_greeter") .model("openai/gpt-4o-mini") .instructions("You are friendly and concise.") .build(); try (AgentRuntime runtime = new AgentRuntime()) { AgentResult result = runtime.run(agent, "Share a fun Java fact."); result.printResult(); }

对这段代码的逐项解读：

• Agent.builder()：流式构建器模式，核心字段为name（Agent 唯一标识，用于后续在工作流中按名调用）、model（LLM 模型，可与CONDUCTOR_AGENT_LLM_MODEL一致或覆盖之）、instructions（系统提示词，决定 Agent 的行为风格）。除此之外，SDK 还支持注册工具（tool）、MCP 工具、guardrail 等能力。
• AgentRuntime实现AutoCloseable：使用 try-with-resources 保证运行结束后释放连接等资源；runtime.run(agent, prompt)返回AgentResult。
• result.printResult()：将 Agent 的最终回答输出到控制台；AgentResult中除了文本，还承载结构化输出与执行元数据。

写好类后，用项目常规的 Gradle 或 Maven application 任务运行即可：

# Gradle ./gradlew run # 或 Maven mvn exec:java -Dexec.mainClass="com.example.MyAgentApp"

运行结束后，回到 Agents 页面即可在 Conductor UI 中看到该次执行被编译成的工作流定义与运行记录。

5. 底层原理：Agent 本质上是一个可持久化的工作流

从仓库的 agents.md 可以看到 Conductor Agent 的核心设计：Agent 起于定义，落于工作流图。

当你执行runtime.run(...)时，Conductor 会把 Agent编译成一个普通的工作流定义并执行它。这个图没有任何特殊性：

• 每一次模型调用是一个任务（LLM task）；
• 每一次工具调用是一个任务（tool task）；
• 两者之间的循环是工作流的控制流（loop）。

正因为一次 Agent 运行就是一次工作流执行，工作流的所有能力全部适用：每一步都被持久化，进程崩溃或重启后从最后一步完成处恢复；重试与超时遵循既有策略；每一步都可以由人工通过 human task 审批或否决；每一次运行都留下完整的、可回放的历史记录。这正是"durable execution"在 Agent 场景的体现。

从源码侧可以印证这一模型：ai模块的 tasks/mapper/AgentTaskMapper.java 负责把 Agent 调用映射为任务，而 tasks/worker/LLMWorkers.java 等 worker 实现则对应图中 LLM 任务与工具任务的执行载体。

6. 验证执行与排障

在 Conductor UI 中定位本次运行产生的 execution，重点检查：

1. 终止状态是否为COMPLETED；
2. 任务时间线中每一次 LLM 调用与工具调用的输入、输出；
3. 若运行无法触达模型，首先核对 worker 环境中的CONDUCTOR_SERVER_URL与模型提供方凭据，然后在 execution 中检查失败任务的详细信息，再决定是否重试。

7. 把 Agent 接入工作流：AGENT 任务

开发期用run一步到位；生产环境中，Agent 遵循create → plan → deploy → serve → run的生命周期（详见 conductor-agents.md）。部署完成后，任何工作流都可以通过AGENT任务调用它：

{ "name": "run_agent", "taskReferenceName": "run_agent_ref", "type": "AGENT", "inputParameters": { "agentType": "conductor", "name": "java_greeter", "prompt": "${workflow.input.prompt}", "pollIntervalSeconds": 5 } }

关键契约：

• agentType是执行模式而非框架：conductor表示运行已部署的 Conductor Agent（按name选择）；a2a（默认）表示调用远端 A2A 端点。
• 首次调用时name与prompt必需；version可固定部署版本，缺省用最新版；sessionId、runId、context、media、model、timeoutSeconds、idempotencyKey按需使用，未提供幂等键时运行时自动生成重启稳定的幂等键。
• 输出契约：AGENT任务写出executionId、agentName、state、text，运行完成时附带结构化output。
• 状态映射：运行态working→ 任务IN_PROGRESS（按pollIntervalSeconds轮询，默认 5 秒）；input-required→COMPLETED（等待人工或工具输入，输出含waiting: true）；completed/failed/canceled分别映射到COMPLETED/FAILED/CANCELED。
• 运行边界：maxDurationSeconds限制整体运行时长（默认 86400 秒），maxPollFailures限制连续瞬时轮询失败次数（默认 30），两者超限都会终态失败并尽力取消子执行。
• 恢复与取消：Agent 等待外部输入时首个AGENT任务会完成而非占用 worker；工作流可通过HUMAN任务收集答案，再用携带executionId与prompt的第二个AGENT任务恢复同一运行；工作流取消会尽力传播到运行中的 Agent。

8. 继续深入

• Your First Agent：多语言（Python / Java / TypeScript / C#）的完整安装与首跑步骤。
• Conductor Agents：Agent 生命周期、AGENT任务完整契约、guardrails 与评估。
• Agent Concepts：Agent 与工作流的组合方式，以及三种编写 Agent 的路径。
• Agent Tool Calling：为 Agent 注册工具的环境变量与调用示例。
• 源码参考：ai/src/main/java/org/conductoross/conductor/ai（模型提供方、任务映射与 Agent 运行时实现）。

【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor