Java SDK for Conductor

The Java SDK for Conductor lets you build durable AI agents and workflow workers. Conductor coordinates retries, state, and observability while your Java code runs wherever you deploy it.

Get involved: ⭐ Conductor OSS · Choose a Conductor OSS contribution · Contribution guide

Using an AI coding agent? Load Conductor Skills so it can create, run, and operate Conductor Workflows and Agents:

npm install -g @conductor-oss/conductor-skills && conductor-skills --all

Choose your path

I want to…	Start here
Build a durable AI agent with tools and human approval	Run an AI agent example
Bring an existing Google ADK or LangChain4j agent	Use framework bridges
Build a durable workflow and Java worker	Run the core hello-world example
Browse all examples	AI agent guide · Core examples
Navigate the SDK documentation	Documentation hub

Choose your Conductor server

Connect to a server before following either quickstart. Use the hosted Developer Edition by default, or run Conductor locally when you need a self-managed development environment.

Recommended: Orkes Developer Edition

Orkes Developer Edition is the default hosted option. Create an application and access key in the Developer Edition UI, then configure this SDK with its API endpoint. Keep the key and secret out of source control.

export CONDUCTOR_SERVER_URL=https://developer.orkescloud.com/api
export CONDUCTOR_AUTH_KEY=<your-key-id>
export CONDUCTOR_AUTH_SECRET=<your-key-secret>

For another hosted or self-managed remote cluster, use that cluster's /api URL and its application credentials instead. See server setup for details.

Local alternative: Conductor CLI

The CLI is the preferred local-server path. It needs Java 21+ and Node.js/npm.

npm install -g @conductor-oss/conductor-cli
conductor server start
conductor server status
export CONDUCTOR_SERVER_URL=http://localhost:8080/api

Docker fallback

Use Docker when you need a containerized local server instead of the CLI:

docker run --rm -p 8080:8080 -p 1234:5000 conductoross/conductor:latest
export CONDUCTOR_SERVER_URL=http://localhost:8080/api

The Docker server UI is available at http://localhost:1234. See server setup for full local, remote, and authentication guidance.

Why Conductor?

• Survive process failures: execution state is durable, so agents and workflows resume from completed work.
• Build dynamic agent graphs: define workflow graphs in Java or let an LLM plan them at runtime. Conductor executes plans as durable sub-workflows, so agents can plan, execute, observe, and replan complex work instead of relying on a transient in-process loop.
• Run tools as distributed tasks: scale Java workers independently while Conductor manages retries and delivery.
• Orchestrate long-running work: combine AI, schedules, events, and human approval without holding application threads open.
• See every execution: inspect inputs, outputs, tool calls, retries, and status through one execution model.

See the real graph: Example115PlannerContext has an LLM turn onboarding policy into a KYC → account → email → conditional kickoff graph. Conductor compiles the plan into a durable sub-workflow, pipes outputs between steps, executes it, and the example reads back the generated sub-workflow to print the actual task trace.

./gradlew :agent-examples:run \
  -PmainClass=org.conductoross.conductor.ai.examples.Example115PlannerContext

Prefer to construct the graph in code? Example108PlanExecuteRefs builds a typed Plan with dependencies and cross-step output references, then runs it through the same durable sub-workflow execution path.

Requirements and compatibility

• Java 21+
• A running OSS/Orkes Conductor server selected in Choose your Conductor server.
• Docker when using the examples/basics/hello-world/run.sh launcher; it builds and runs the example in containers even when the server itself is remote or CLI-managed.
• Maven 3.8+ when running standalone core examples without their launcher script; Gradle is included for this repository's agent examples.

The CI workflows are the source of truth for the server versions exercised by this SDK. See the agent E2E matrix for its pinned server version.

Install the SDK

Replace <VERSION> with a published version from Maven Central.

AI agents

dependencies {
    implementation 'org.conductoross:conductor-client-ai:<VERSION>'
}

<dependency>
    <groupId>org.conductoross</groupId>
    <artifactId>conductor-client-ai</artifactId>
    <version>&lt;VERSION&gt;</version>
</dependency>

Google ADK and LangChain4j are optional dependencies; use the versions and setup in the Google ADK guide or LangChain4j guide.

Workflows and workers

dependencies {
    implementation 'org.conductoross:conductor-client:<VERSION>'
}

<dependency>
    <groupId>org.conductoross</groupId>
    <artifactId>conductor-client</artifactId>
    <version>&lt;VERSION&gt;</version>
</dependency>

Modules

Module	Use it for
conductor-client-ai	Durable AI agents, tools, guardrails, handoffs, and framework bridges
conductor-client-ai-spring	Spring auto-configuration for AI agents
conductor-client	Workflow, task, worker, metadata, and scheduler clients
conductor-client-spring	Spring auto-configuration for the core client
conductor-client-spring-boot4	Spring Boot 4 auto-configuration for the core client
conductor-client-metrics	Prometheus metrics collection

AI agent quickstart

Use this path when your agent needs LLM reasoning, tools, guardrails, handoffs, or human approval. Select a server above first. For a local CLI server, configure the LLM provider credential in the server environment before starting it. For Developer Edition, configure the provider integration in the hosted cluster. The agent getting-started guide covers both paths.

export CONDUCTOR_AGENT_LLM_MODEL=openai/gpt-4o-mini

# Run the maintained basic-agent example from this repository.
./gradlew :agent-examples:run \
  -PmainClass=org.conductoross.conductor.ai.examples.Example01BasicAgent

Expected outcome: the example prints an AgentResult containing the model response. See the AI agent guide, tools guide, and agent examples for the next step.

Google ADK and LangChain4j

Keep using the Java agent framework your team already knows. The SDK bridges native Google ADK BaseAgent and LlmAgent instances into durable Conductor agents, including tools and sub-agent graphs. It also turns existing LangChain4j @Tool-annotated POJOs into Conductor worker tools and supports LangChain4j ChatModel-based agents.

Start with the Google ADK examples or the focused LangChain4j bridge guide.

Workflow and worker quickstart

With a server selected above, this maintained example registers a workflow, starts a Java worker, executes the workflow, and prints Result: PASSED.

cd examples/basics/hello-world
./run.sh

Expected outcome:

Status: COMPLETED
Output: {greeting=Hello, Developer! Welcome to Conductor.}
Result: PASSED

The launcher requires Docker to build and run the example. With CONDUCTOR_SERVER_URL set, it reuses the selected remote, CLI-managed, or Docker server. If you leave it unset, the launcher starts its own Docker Compose server; stop that server with docker compose down from examples/basics/hello-world.

For worker patterns, workflow definitions, and testing, continue with the core examples catalog, worker guide, and workflow guide.

Common tasks

Need	Start with
Build Java AI agents	Agent concepts
Add tools and human approval	Agent tools
Use another agent framework	Google ADK · LangChain4j · LangGraph4j
Deploy, serve, and run agents	Agent runtime modes
Implement and scale Java workers	Workers guide · reliability
Define and evolve workflows	Workflows guide · lifecycle/versioning
Upload/download workflow-scoped files	FileClient guide
Test workflows and workers	Workflow test harness
Expose worker metrics	Client metrics
Configure Spring applications	Boot 3 · Boot 4 · AI Spring guide
Manage schedules and events	Schedules/events guide
Find typed clients and Javadocs	Core API map

Troubleshooting

Symptom	Check
Connection refused	The server is healthy at http://localhost:8080/health; CONDUCTOR_SERVER_URL ends in /api.
Task remains SCHEDULED	A worker is polling the exact task type and has enough threads.
Authentication failure	CONDUCTOR_AUTH_KEY and CONDUCTOR_AUTH_SECRET are set for the target server.
AI agent cannot call a model	The server—not only the client process—has a configured LLM provider and model.

Support and project policies

Contribute upstream: Choose a Conductor OSS contribution · Read the Conductor OSS contribution guide

• SDK issues for Java SDK bugs and feature requests
• Conductor server issues for OSS server behavior
• Contributing for local development, tests, and pull requests
• Code of Conduct for community expectations and conduct reporting
• Security policy for private vulnerability reporting
• Conductor Slack and the Orkes Community Forum for questions

License

Apache 2.0. See LICENSE.