conductor-sdk 0.2.0

Rust SDK for Netflix Conductor workflow orchestration
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
# Rust SDK for Conductor

[![CI](https://github.com/conductor-oss/rust-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/conductor-oss/rust-sdk/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/conductor-sdk.svg)](https://crates.io/crates/conductor-sdk)
[![Rust Versions](https://img.shields.io/badge/rust-1.85%2B-blue.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/crates/l/conductor-sdk.svg)](LICENSE)

Build agents, workflows, and workers in Rust with [Conductor](https://www.conductor-oss.org/).

See the [agent quickstart](#agent-quickstart) or [workflow quickstart](#60-second-quickstart).
[Conductor Skills](https://github.com/conductor-oss/conductor-skills) helps coding agents work with Conductor.

## Choose your Conductor server

Use a hosted or local Conductor server for the examples below.

### Recommended: Orkes Developer Edition

In [Orkes Developer Edition](https://developer.orkescloud.com/), create an application and access key, then set:

```shell
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 remote cluster, use its `/api` URL and credentials.

### Local: Conductor CLI

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

### Local: Docker Compose

```shell
docker compose -f scripts/docker-compose-oss.yaml up -d
export CONDUCTOR_SERVER_URL=http://localhost:8080/api
```

The Compose server UI is at [http://localhost:8080](http://localhost:8080).

Requires Rust 1.85 or newer and a reachable Conductor server. See [CI](.github/workflows/ci.yml) for tested server versions.

## Install the SDK

Add the following to your `Cargo.toml`:

```toml
[dependencies]
# The crate is published as `conductor-sdk`; rename it to `conductor` so
# `use conductor::...` works in your code.
conductor = { version = "0.2.0", package = "conductor-sdk" }
tokio = { version = "1", features = ["full"] }
```

For the `#[worker]` macro (similar to Python's `@worker_task` decorator):

```toml
[dependencies]
conductor = { version = "0.2.0", package = "conductor-sdk", features = ["macros"] }
conductor-macros = "0.2.0"
tokio = { version = "1", features = ["full"] }
```

For agents, enable `agents`:

```toml
conductor = { version = "0.2.0", package = "conductor-sdk", features = ["agents"] }
tokio = { version = "1", features = ["full"] }
```

The [`agents` feature](Cargo.toml) includes worker macros.

## Agent quickstart

Configure a provider and model on your Conductor server. Create a project and add the `agents` dependencies above to its `Cargo.toml`:

```shell
cargo new conductor-agent-demo
cd conductor-agent-demo
```

Put this in `src/main.rs`:

```rust
use conductor::agents::{AgentDef, AgentRuntime};
use conductor::configuration::Configuration;
use conductor::error::{ConductorError, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let model = std::env::args().nth(1).ok_or_else(|| {
        ConductorError::agent("Pass a configured provider/model as the first argument")
    })?;
    if model.trim().is_empty() {
        return Err(ConductorError::agent("Model argument cannot be empty"));
    }
    let config = Configuration::from_env();
    let runtime = AgentRuntime::new(config)?;

    let agent = AgentDef::new("greeter")?
        .with_model(model)
        .with_instructions("You are a friendly assistant. Keep responses brief.");

    let result = runtime
        .run(
            &agent,
            "Say hello and tell me a fun fact about Python.".into(),
        )
        .await?;

    println!("status: {}", result.status);
    println!("output: {}", result.output);
    println!("execution_id: {}", result.execution_id);
    if !result.is_success() {
        return Err(ConductorError::agent(format!(
            "Agent execution ended with status {}",
            result.status
        )));
    }
    Ok(())
}
```

Run with a model configured on your server:

```shell
cargo run -- openai/gpt-4o-mini
```

The [checked-in example](examples/agent_quickstart.rs) uses the same code.
Expect `status: COMPLETED`, model output, and an execution ID.

See the [agent guide](docs/agents/README.md) and [examples](docs/agents/examples.md) for more.

## 60-Second Quickstart

**Step 1: Create a workflow**

Workflows are definitions that reference task types (e.g. a SIMPLE task called `greet`). We'll build a workflow called
`greetings` that runs one task and returns its output.

```rust
use conductor::models::{WorkflowDef, WorkflowTask};

fn greetings_workflow() -> WorkflowDef {
    WorkflowDef::new("greetings")
        .with_version(1)
        .with_task(
            WorkflowTask::simple("greet", "greet_ref")
                .with_input_param("name", "${workflow.input.name}")
        )
        .with_output_param("result", "${greet_ref.output.result}")
}
```

**Step 2: Write worker**

Workers are Rust functions decorated with `#[worker]` that poll Conductor for tasks and execute them.

```rust
use conductor_macros::worker;

#[worker(name = "greet")]
async fn greet(name: String) -> String {
    format!("Hello {}", name)
}
```

**Step 3: Run your first workflow app**

Create a Cargo project, add the macro dependencies above to its `Cargo.toml`, then put the following in `src/main.rs`:

```shell
cargo new greetings
cd greetings
```

```rust
use conductor::{
    client::ConductorClient,
    configuration::Configuration,
    models::{StartWorkflowRequest, WorkflowDef, WorkflowTask},
    worker::TaskHandler,
};
use conductor_macros::worker;

// A worker is any Rust function with the #[worker] macro.
#[worker(name = "greet")]
async fn greet(name: String) -> String {
    format!("Hello {}", name)
}

fn greetings_workflow() -> WorkflowDef {
    WorkflowDef::new("greetings")
        .with_version(1)
        .with_task(
            WorkflowTask::simple("greet", "greet_ref")
                .with_input_param("name", "${workflow.input.name}")
        )
        .with_output_param("result", "${greet_ref.output.result}")
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure the SDK (reads CONDUCTOR_SERVER_URL / CONDUCTOR_AUTH_* from env).
    let config = Configuration::default();
    let client = ConductorClient::new(config.clone())?;

    // Register the workflow
    let workflow = greetings_workflow();
    client.metadata_client()
        .register_or_update_workflow_def(&workflow, true)
        .await?;

    // Start polling for tasks
    let mut task_handler = TaskHandler::new(config.clone())?;
    task_handler.add_worker(greet_worker());
    task_handler.start().await?;

    // Run the workflow and get the result
    let run = client.workflow_client()
        .execute_workflow(
            &StartWorkflowRequest::new("greetings")
                .with_version(1)
                .with_input_value("name", "Conductor"),
            std::time::Duration::from_secs(10),
        )
        .await?;

    println!("result: {:?}", run.output.get("result"));
    println!("execution: {}/execution/{}", config.ui_host, run.workflow_id);

    task_handler.stop().await?;
    Ok(())
}
```

Run it:

```shell
cargo run
```

> ### Using Orkes Conductor / Remote Server?
> Export your authentication credentials as well:
>
> ```shell
> export CONDUCTOR_SERVER_URL="https://your-cluster.orkesconductor.io/api"
>
> # If using Orkes Conductor that requires auth key/secret
> export CONDUCTOR_AUTH_KEY="your-key"
> export CONDUCTOR_AUTH_SECRET="your-secret"
> ```
> See [Choose your Conductor server]#choose-your-conductor-server for setup details.

That's it -- you just defined a worker, built a workflow, and executed it. Open the Conductor UI (default:
[http://localhost:8080](http://localhost:8080)) to see the execution.

## Comprehensive worker example

The example includes sync + async workers, metrics, and long-running tasks.

See [examples/worker_example.rs](examples/worker_example.rs)

---

## Workers

Workers are Rust functions that execute Conductor tasks. Use the `#[worker]` macro or `FnWorker` to:

- register it as a worker (auto-discovered by `TaskHandler`)
- use it as a workflow task (call it with `task_ref_name=...`)

Workers can also serve as agent tools. See [Conductor agents](#conductor-agents).

```rust
use conductor_macros::worker;

#[worker(name = "greet")]
async fn greet(name: String) -> String {
    format!("Hello {}", name)
}
```

**Using FnWorker (closure-based):**

```rust
use conductor::worker::{FnWorker, WorkerOutput};

let greetings_worker = FnWorker::new("greetings", |task| async move {
    let name = task.get_input_string("name").unwrap_or_default();
    Ok(WorkerOutput::completed_with_result(format!("Hello, {}", name)))
})
.with_thread_count(10)
.with_poll_interval_millis(100);
```

**Start workers** with `TaskHandler`:

```rust
use conductor::{
    configuration::Configuration,
    worker::TaskHandler,
};

let config = Configuration::default();
let mut task_handler = TaskHandler::new(config)?;
task_handler.add_worker(greet_worker());

task_handler.start().await?;

// Wait for shutdown signal
tokio::signal::ctrl_c().await?;

task_handler.stop().await?;
```

**Worker Configuration**

Workers support hierarchical environment variable configuration — global settings that can be overridden per worker:

```shell
# Global (all workers)
export CONDUCTOR_WORKER_ALL_POLL_INTERVAL_MILLIS=250
export CONDUCTOR_WORKER_ALL_THREAD_COUNT=20
export CONDUCTOR_WORKER_ALL_DOMAIN=production

# Per-worker override
export CONDUCTOR_WORKER_GREETINGS_THREAD_COUNT=50
```

See [WORKER_CONFIGURATION.md](WORKER_CONFIGURATION.md) for all options.

## Monitoring Workers

Enable Prometheus metrics:

```rust
use conductor::metrics::MetricsSettings;
use conductor::worker::TaskHandler;

let mut task_handler = TaskHandler::new(config)?;
task_handler.enable_metrics(
    MetricsSettings::new()
        .with_http_port(9090)
);

task_handler.start().await?;
// Metrics at http://localhost:9090/metrics
```

See [METRICS.md](METRICS.md) for details.

**Learn more:**
- [Worker Guide]docs/WORKER.md — All worker patterns (function, closure, macro, async)
- [Worker Configuration]WORKER_CONFIGURATION.md — Environment variable configuration system

## Workflows

Define workflows in Rust using the builder pattern to chain tasks:

```rust
use conductor::{
    client::ConductorClient,
    configuration::Configuration,
    models::{WorkflowDef, WorkflowTask},
};

let config = Configuration::default();
let client = ConductorClient::new(config)?;
let metadata_client = client.metadata_client();

let workflow = WorkflowDef::new("greetings")
    .with_version(1)
    .with_task(
        WorkflowTask::simple("greet", "greet_ref")
            .with_input_param("name", "${workflow.input.name}")
    )
    .with_output_param("result", "${greet_ref.output.result}");

// Registering is required if you want to start/execute by name+version
metadata_client.register_or_update_workflow_def(&workflow, true).await?;
```

**Execute workflows:**

```rust
use conductor::models::StartWorkflowRequest;
use std::time::Duration;

// Asynchronous (returns workflow ID immediately)
let request = StartWorkflowRequest::new("greetings")
    .with_version(1)
    .with_input_value("name", "Orkes");
let workflow_id = workflow_client.start_workflow(&request).await?;

// Synchronous (waits for completion)
let run = workflow_client
    .execute_workflow(&request, Duration::from_secs(10))
    .await?;
println!("{:?}", run.output);
```

**Manage running workflows and send signals:**

```rust
workflow_client.pause_workflow(&workflow_id).await?;
workflow_client.resume_workflow(&workflow_id).await?;
workflow_client.terminate_workflow(&workflow_id, Some("no longer needed"), false).await?;
workflow_client.retry_workflow(&workflow_id, false).await?;
workflow_client.restart_workflow(&workflow_id, false).await?;
```

**Learn more:**
- [Workflow Management]docs/WORKFLOW.md — Start, pause, resume, terminate, retry, search
- [Workflow Testing]examples/test_workflows.rs — Example using mock task outputs
- [Metadata Management]docs/METADATA.md — Task & workflow definitions

## Troubleshooting

- **Worker stops polling**: `TaskHandler` monitors workers. Use `task_handler.is_healthy()` for health checks.
- **Connection issues**: Verify `CONDUCTOR_SERVER_URL` is correct and server is running.
- **Authentication failures**: For Orkes Conductor, ensure `CONDUCTOR_AUTH_KEY` and `CONDUCTOR_AUTH_SECRET` are valid.
- **Agent cannot call a model**: Check the provider and model configured on the Conductor server.

---

## Conductor agents

The `agents` feature supports local tools, human approval, guardrails, and multi-agent runs.
Configure a model on your Conductor server, then try:

| Example | Shows |
|---|---|
| [Simple tools]examples/agent_demo_02a_simple_tools.rs | Rust function tools |
| [Human approval]examples/agent_demo_09_human_in_the_loop.rs | Terminal approval for a tool call |
| [Parallel agents]examples/agent_demo_07_parallel_agents.rs | Multi-agent execution |

```shell
cargo run --example agent_demo_02a_simple_tools --features agents -- openai/gpt-4o-mini
```

See the [agent guide](docs/agents/README.md) and [full example list](docs/agents/examples.md).
For LLM and RAG workflows built with the core SDK, see [llm_chat_example.rs](examples/llm_chat_example.rs)
and [rag_workflow.rs](examples/rag_workflow.rs).

## Examples

See the examples directory for the full catalog. Key examples:

| Example | Description | Run |
|---------|-------------|-----|
| [worker_example.rs]examples/worker_example.rs | End-to-end: sync + async workers, metrics | `cargo run --example worker_example` |
| [hello_world.rs]examples/hello_world.rs | Minimal hello world | `cargo run --example hello_world` |
| [dynamic_workflow.rs]examples/dynamic_workflow.rs | Build workflows programmatically | `cargo run --example dynamic_workflow` |
| [llm_chat_example.rs]examples/llm_chat_example.rs | AI multi-turn chat | `cargo run --example llm_chat_example` |
| [rag_workflow.rs]examples/rag_workflow.rs | RAG pipeline | `cargo run --example rag_workflow` |
| [task_context_example.rs]examples/task_context_example.rs | Long-running tasks with TaskContext | `cargo run --example task_context_example` |
| [workflow_ops.rs]examples/workflow_ops.rs | Pause, resume, terminate workflows | `cargo run --example workflow_ops` |
| [test_workflows.rs]examples/test_workflows.rs | Unit testing workflows | `cargo run --example test_workflows` |
| [kitchensink.rs]examples/kitchensink.rs | All task types (HTTP, JS, JQ, Switch) | `cargo run --example kitchensink` |

## API Journey Examples

End-to-end examples covering all APIs for each domain:

| Example | APIs | Run |
|---------|------|-----|
| [authorization_example.rs]examples/authorization_example.rs | Authorization APIs | `cargo run --example authorization_example` |
| [metadata_journey.rs]examples/metadata_journey.rs | Metadata APIs | `cargo run --example metadata_journey` |
| [schedule_journey.rs]examples/schedule_journey.rs | Schedule APIs | `cargo run --example schedule_journey` |
| [prompt_journey.rs]examples/prompt_journey.rs | Prompt APIs | `cargo run --example prompt_journey` |

## Documentation

| Document | Description |
|----------|-------------|
| [Worker Guide]docs/WORKER.md | All worker patterns (function, closure, macro, async) |
| [Agent Guide]docs/agents/README.md | Durable agents, tools, and runtime modes |
| [Worker Configuration]WORKER_CONFIGURATION.md | Hierarchical environment variable configuration |
| [Workflow Management]docs/WORKFLOW.md | Start, pause, resume, terminate, retry, search |
| [Workflow Testing]examples/test_workflows.rs | Example using mock task outputs |
| [Task Management]docs/TASK_MANAGEMENT.md | Task operations |
| [Metadata]docs/METADATA.md | Task & workflow definitions |
| [Authorization]docs/AUTHORIZATION.md | Users, groups, applications, permissions |
| [Schedules]docs/SCHEDULE.md | Workflow scheduling |
| [Secrets]docs/SECRET_MANAGEMENT.md | Secret storage |
| [Prompts]docs/PROMPT.md | AI/LLM prompt templates |
| [Integrations]docs/INTEGRATION.md | AI/LLM provider integrations |
| [Metrics]METRICS.md | Prometheus metrics collection |

## Support

- [Open an issue (SDK)]https://github.com/conductor-oss/rust-sdk/issues for SDK bugs, questions, and feature requests
- [Open an issue (Conductor server)]https://github.com/conductor-oss/conductor/issues for Conductor OSS server issues
- [Join the Conductor Slack]https://join.slack.com/t/orkes-conductor/shared_invite/zt-2vdbx239s-Eacdyqya9giNLHfrCavfaA for community discussion and help
- [Orkes Community Forum]https://community.orkes.io/ for Q&A
- [Conductor OSS contribution guide]https://github.com/conductor-oss/conductor/blob/main/CONTRIBUTING.md for contributing upstream
- [Conductor Code of Conduct]https://github.com/conductor-oss/conductor/blob/main/CODE_OF_CONDUCT.md and [security policy]https://github.com/conductor-oss/conductor/security/policy for community and private vulnerability reporting

## Frequently Asked Questions

**Is this the same as Netflix Conductor?**

Yes. Conductor OSS is the continuation of the original [Netflix Conductor](https://github.com/Netflix/conductor) repository after Netflix contributed the project to the open-source foundation.

**Is this project actively maintained?**

Yes. [Orkes](https://orkes.io) is the primary maintainer and offers an enterprise SaaS platform for Conductor across all major cloud providers.

**Can Conductor scale to handle my workload?**

Conductor was built at Netflix to handle massive scale and has been battle-tested in production environments processing millions of workflows. It scales horizontally to meet virtually any demand.

**Does Conductor support durable code execution?**

Yes. Conductor ensures workflows complete reliably even in the face of infrastructure failures, process crashes, or network issues.

**Are workflows always asynchronous?**

No. While Conductor excels at asynchronous orchestration, it also supports synchronous workflow execution when immediate results are required.

**Do I need to use a Conductor-specific framework?**

No. Conductor is language and framework agnostic. Use your preferred language and framework -- the [SDKs](https://github.com/conductor-oss/conductor#conductor-sdks) provide native integration for Python, Java, JavaScript, Go, C#, Rust, and more.

**Can I mix workers written in different languages?**

Yes. A single workflow can have workers written in Rust, Python, Java, Go, or any other supported language. Workers communicate through the Conductor server, not directly with each other.

**What Rust versions are supported?**

Rust 1.85 and above (2021 edition), as declared in `Cargo.toml`.

**Should I use `async fn` or regular `fn` for my workers?**

Use `async fn` for I/O-bound tasks (API calls, database queries) — the SDK uses async runtime for high concurrency with low overhead. Use regular functions for CPU-bound or blocking work. The SDK handles both patterns efficiently.

**How do I run workers in production?**

Workers are standard Rust applications. Deploy them as you would any Rust application -- in containers, VMs, or bare metal. Workers poll the Conductor server for tasks, so no inbound ports need to be opened.

**How do I test workflows with mock task outputs?**

Conductor's `POST /api/workflow/test` endpoint evaluates workflows with mock task outputs. See the [workflow testing example](examples/test_workflows.rs). This endpoint still requires a running Conductor server.

## License

Apache 2.0