conductor-oss · NicholasDCole · Jul 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Durable AI agents** -- the Agentspan TypeScript SDK (`@conductor-oss/conductor-agent-sdk`) is merged into this package as new subpath exports: `@io-orkes/conductor-javascript/agents` (core: `Agent`, `AgentRuntime`, `tool`, guardrails, handoffs, memory, schedules, streaming, HITL), `/agents/testing`, and framework wrappers `/agents/vercel-ai`, `/agents/langgraph`, `/agents/langchain`. The agent clients are also first-class citizens of the root export (`AgentClient`, `WorkflowClient`, `Schedule`, `ScheduleInfo`, schedule errors) — the root surface grows additively (minor). Docs at [docs/agents/](docs/agents/README.md); 60+ examples at [examples/agents/](examples/agents/).
+- **Durable AI agents** -- the Agentspan TypeScript SDK (`@conductor-oss/conductor-agent-sdk`) is merged into this package as new subpath exports: `@io-orkes/conductor-javascript/agents` (core: `Agent`, `AgentRuntime`, `tool`, guardrails, handoffs, memory, schedules, streaming, HITL), `/agents/testing`, and framework wrappers `/agents/vercel-ai`, `/agents/langgraph`, `/agents/langchain`. The agent clients are also first-class citizens of the root export (`AgentClient`, `WorkflowClient`, `Schedule`, `ScheduleInfo`, schedule errors) — the root surface grows additively (minor). Docs at [docs/agents/](docs/agents/README.md); 200+ examples at [examples/agents/](examples/agents/).
   - **Migration for `@conductor-oss/conductor-agent-sdk` users:** install `@io-orkes/conductor-javascript` and rewrite import specifiers -- `@conductor-oss/conductor-agent-sdk` becomes `@io-orkes/conductor-javascript/agents`, and the wrapper subpaths gain the `/agents` prefix (e.g. `.../vercel-ai` becomes `.../agents/vercel-ai`).
   - New optional peer dependencies (all lazily resolved, install only what you use): `zod`, `zod-to-json-schema`, `ai`, `@langchain/core`, `@langchain/langgraph`. `dotenv` becomes a runtime dependency (the agent entry points load it at import time; the package `sideEffects` field allowlists `dist/agents/**` so bundlers keep that bootstrap).
 - **Agent clients in `sdk/clients`, one client for both planes** -- `AgentClient` is an interface (the `/agent/*` control-plane surface); `OrkesAgentClient` is the implementation, obtained via `runtime.client` or `OrkesClients.getAgentClient()`. Both share a single underlying `ConductorClient` (and its one token mint) across control-plane and worker-plane calls -- no bespoke agent-layer auth/transport code exists. Naming note: `getWorkflowClient()` returns the general-purpose `WorkflowExecutor`; the agent `WorkflowClient` (`OrkesClients.getAgentClient().workflows` / `getAgentWorkflowClient()`) adds the agent-execution 404 fallback and token-usage rollup.

diff --git a/README.md b/README.md
@@ -459,7 +459,7 @@ See the [Examples Guide](examples/README.md) for the full catalog. Key examples:
 | [test-workflows.ts](examples/test-workflows.ts) | Unit testing with mock outputs (no workers) | `npx ts-node examples/test-workflows.ts` |
 | [metrics.ts](examples/metrics.ts) | Prometheus metrics + HTTP server on :9090 | `npx ts-node examples/metrics.ts` |
 | [express-worker-service.ts](examples/express-worker-service.ts) | Express.js + workers in one process | `npx ts-node examples/express-worker-service.ts` |
-| [function-calling.ts](examples/agentic-workflows/function-calling.ts) | LLM dynamically picks which worker to call | `npx ts-node examples/agentic-workflows/function-calling.ts` |
+| [02-tools.ts](examples/agents/02-tools.ts) | Durable agent: LLM dynamically picks which tool to call | `npx tsx examples/agents/02-tools.ts` |
 | [fork-join.ts](examples/advanced/fork-join.ts) | Parallel branches with join synchronization | `npx ts-node examples/advanced/fork-join.ts` |
 | [sub-workflows.ts](examples/advanced/sub-workflows.ts) | Workflow composition with sub-workflows | `npx ts-node examples/advanced/sub-workflows.ts` |
 | [human-tasks.ts](examples/advanced/human-tasks.ts) | Human-in-the-loop: claim, update, complete | `npx ts-node examples/advanced/human-tasks.ts` |
@@ -518,18 +518,20 @@ const run = await workflow.execute({ question: "What is Conductor?" });
 console.log(run.output?.answer);
 ```
 
-**Agentic Workflows**
+**Agentic Examples**
 
-Build AI agents where LLMs dynamically select and call TypeScript workers as tools.
-See [examples/agentic-workflows/](examples/agentic-workflows/) for all examples.
+To build AI agents where LLMs dynamically select and call tools, use the
+durable agents layer (see [Durable AI Agents](#durable-ai-agents) below).
+All agent examples live in [examples/agents/](examples/agents/); highlights:
 
 | Example | Description |
 |---------|-------------|
-| [llm-chat.ts](examples/agentic-workflows/llm-chat.ts) | Automated multi-turn conversation between two LLMs |
-| [llm-chat-human-in-loop.ts](examples/agentic-workflows/llm-chat-human-in-loop.ts) | Interactive chat with WAIT tasks for human input |
-| [function-calling.ts](examples/agentic-workflows/function-calling.ts) | LLM dynamically picks which worker function to call |
-| [mcp-weather-agent.ts](examples/agentic-workflows/mcp-weather-agent.ts) | MCP tool discovery and invocation for real-time data |
-| [multiagent-chat.ts](examples/agentic-workflows/multiagent-chat.ts) | Multi-agent debate: optimist vs skeptic with moderator |
+| [01-basic-agent.ts](examples/agents/01-basic-agent.ts) | Simplest possible agent: define, run, print result |
+| [02-tools.ts](examples/agents/02-tools.ts) | LLM dynamically picks which tool to call, incl. approval-required tools |
+| [03-multi-agent.ts](examples/agents/03-multi-agent.ts) | Multi-agent orchestration: sequential, parallel, handoffs |
+| [04-mcp-weather.ts](examples/agents/04-mcp-weather.ts) | MCP tool discovery and invocation for real-time data |
+| [09-human-in-the-loop.ts](examples/agents/09-human-in-the-loop.ts) | Agent pauses for human approval mid-run |
+| [15-agent-discussion.ts](examples/agents/15-agent-discussion.ts) | Multi-turn debate between agents with opposing viewpoints |
 
 **RAG and Vector DB Workflows**
 
@@ -572,9 +574,11 @@ testing toolkit (`/agents/testing`).
 
 - **Docs:** [docs/agents/](docs/agents/README.md) — start with
   [getting-started.md](docs/agents/getting-started.md)
-- **Examples:** [examples/agents/](examples/agents/) — 60+ runnable examples,
-  from a basic agent to the full [kitchen sink](examples/agents/kitchen-sink.ts);
-  run them with `npx tsx examples/agents/01-basic-agent.ts`
+- **Examples:** [examples/agents/](examples/agents/) — 200+ runnable examples
+  (core examples plus quickstart and framework ports for Google ADK, LangGraph,
+  OpenAI Agents SDK, and Vercel AI SDK), from a basic agent to the full
+  [kitchen sink](examples/agents/kitchen-sink.ts); run them with
+  `npx tsx examples/agents/01-basic-agent.ts`
 
 ## Documentation
 

diff --git a/SDK_DEVELOPMENT.md b/SDK_DEVELOPMENT.md
@@ -603,24 +603,24 @@ Read in `resolveOrkesConfig.ts`. Env vars take precedence over config object val
 
 ## Examples
 
-The `examples/` directory contains 32 runnable TypeScript files across 3 subdirectories, matching the Python SDK's examples structure. See [examples/README.md](examples/README.md) for the full catalog.
+The `examples/` directory contains 31 runnable TypeScript files for the workflow/worker layer, plus 200+ durable AI-agent examples under `examples/agents/`. See [examples/README.md](examples/README.md) for the full catalog.
 
 ### Structure
 
 ```
 examples/
-├── 13 core files          # Workers, workflows, metrics, testing
-├── agentic-workflows/     # 5 AI/LLM agent examples
-├── api-journeys/          # 7 complete API lifecycle demos
-└── advanced/              # 7 advanced workflow patterns
+├── 14 core files          # Workers, workflows, metrics, testing
+├── agents/                # 200+ durable AI agent examples (see examples/agents/README.md)
+├── api-journeys/          # 9 complete API lifecycle demos
+└── advanced/              # 8 advanced workflow patterns
 ```
 
 ### Conventions
 
 - **Self-contained**: Every file imports from `../src/sdk`, connects via `OrkesClients.from()`, and is runnable with `npx ts-node examples/<file>.ts`
 - **Cleanup**: Examples that create resources clean up after themselves in try/finally blocks
 - **Env vars**: All examples read `CONDUCTOR_SERVER_URL` (required) and optionally `CONDUCTOR_AUTH_KEY`/`CONDUCTOR_AUTH_SECRET`
-- **AI examples**: Use `LLM_PROVIDER` and `LLM_MODEL` env vars with defaults to `openai_integration` / `gpt-4o`
+- **Agent examples**: `examples/agents/` uses `AGENTSPAN_SERVER_URL`/`AGENTSPAN_LLM_MODEL` plus a provider API key — see [examples/agents/README.md](examples/agents/README.md)
 - **Naming**: Kebab-case file names matching Python SDK's snake_case pattern (e.g., `fork-join.ts` ↔ `fork_join_script.py`)
 - **Imports**: Use relative paths from the example file (e.g., `from "../../src/sdk"` for subdirectory examples)
 
@@ -665,8 +665,6 @@ examples/
 | `api-journeys/metadata.ts` | `metadata_journey.py` | All metadata APIs |
 | `api-journeys/prompts.ts` | `prompt_journey.py` | All prompt APIs |
 | `api-journeys/schedules.ts` | `schedule_journey.py` | All schedule APIs |
-| `agentic-workflows/function-calling.ts` | `agentic_workflows/function_calling_example.py` | LLM tool calling |
-| `agentic-workflows/multiagent-chat.ts` | `agentic_workflows/multiagent_chat.py` | Multi-agent debate |
 | `advanced/rag-workflow.ts` | `rag_workflow.py` | RAG pipeline |
 | `advanced/fork-join.ts` | `orkes/fork_join_script.py` | Parallel execution |
 

diff --git a/SDK_NEW_LANGUAGE_GUIDE.md b/SDK_NEW_LANGUAGE_GUIDE.md
@@ -1417,7 +1417,7 @@ const wf = new ConductorWorkflow(executor, "my_workflow")
 
 ### Phase 7: Examples
 
-**Goal:** 36 runnable example files demonstrating all SDK features.
+**Goal:** 31 runnable example files demonstrating all SDK features.
 
 #### 7.1 Core Examples (14 files)
 
@@ -1451,15 +1451,20 @@ const wf = new ConductorWorkflow(executor, "my_workflow")
 | `advanced/wait-for-webhook.ts` | Webhook wait pattern |
 | `advanced/human-tasks.ts` | Human-in-the-loop workflow |
 
-#### 7.3 Agentic / AI Examples (5 files)
+#### 7.3 Agentic / AI Examples
+
+Agentic examples (tool calling, multi-agent, human-in-the-loop, MCP) are
+provided by the durable agents layer under `examples/agents/` in the JS SDK
+(200+ examples) rather than as hand-built LLM-task workflows. If the new-language SDK includes
+an agents layer, mirror that catalog — e.g.:
 
 | File | Demonstrates |
 |------|-------------|
-| `agentic-workflows/function-calling.ts` | LLM tool/function calling |
-| `agentic-workflows/multiagent-chat.ts` | Multi-agent debate |
-| `agentic-workflows/llm-chat.ts` | LLM chat completion |
-| `agentic-workflows/llm-chat-human-in-loop.ts` | Human-in-the-loop AI |
-| `agentic-workflows/mcp-weather-agent.ts` | MCP tool integration |
+| `agents/01-basic-agent.ts` | Basic LLM agent |
+| `agents/02-tools.ts` | LLM tool/function calling |
+| `agents/03-multi-agent.ts` | Multi-agent orchestration |
+| `agents/09-human-in-the-loop.ts` | Human-in-the-loop AI |
+| `agents/04-mcp-weather.ts` | MCP tool integration |
 
 #### 7.4 API Journey Examples (9 files)
 

diff --git a/examples/README.md b/examples/README.md
@@ -2,7 +2,7 @@
 
 Quick reference for example files demonstrating SDK features.
 
-> **Looking for the durable AI-agent examples?** They live in
+> **Looking for the durable AI-agent examples?** All 200+ of them live in
 > [`agents/`](agents/) and demonstrate the `@io-orkes/conductor-javascript/agents`
 > layer (`Agent`, `AgentRuntime`, tools, guardrails, handoffs) — run them with
 > `npx tsx examples/agents/01-basic-agent.ts`. The examples in this directory
@@ -44,17 +44,21 @@ npx ts-node examples/workers-e2e.ts
 | **[workflow-ops.ts](workflow-ops.ts)** | Lifecycle: start, pause, resume, terminate, restart, retry, search | `npx ts-node examples/workflow-ops.ts` |
 | **[test-workflows.ts](test-workflows.ts)** | Unit testing with mock task outputs (no workers needed) | `npx ts-node examples/test-workflows.ts` |
 
-### AI/LLM Workflows
+### AI Agents
 
-Require an LLM integration configured in Conductor. Set `LLM_PROVIDER` and `LLM_MODEL` env vars.
+Agentic examples live in [`agents/`](agents/) and use the durable agents layer
+(`@io-orkes/conductor-javascript/agents`). See [agents/README.md](agents/README.md)
+for the full catalog and environment setup (`AGENTSPAN_SERVER_URL`,
+`AGENTSPAN_LLM_MODEL`, provider API key). Highlights:
 
 | File | Description | Run |
 |------|-------------|-----|
-| **[agentic-workflows/llm-chat.ts](agentic-workflows/llm-chat.ts)** | Two LLMs in automated multi-turn conversation | `npx ts-node examples/agentic-workflows/llm-chat.ts` |
-| **[agentic-workflows/llm-chat-human-in-loop.ts](agentic-workflows/llm-chat-human-in-loop.ts)** | Interactive chat with WAIT tasks for human input | `npx ts-node examples/agentic-workflows/llm-chat-human-in-loop.ts` |
-| **[agentic-workflows/function-calling.ts](agentic-workflows/function-calling.ts)** | LLM dynamically picks which worker to call | `npx ts-node examples/agentic-workflows/function-calling.ts` |
-| **[agentic-workflows/mcp-weather-agent.ts](agentic-workflows/mcp-weather-agent.ts)** | MCP tool discovery + invocation for real-time data | `npx ts-node examples/agentic-workflows/mcp-weather-agent.ts` |
-| **[agentic-workflows/multiagent-chat.ts](agentic-workflows/multiagent-chat.ts)** | Multi-agent debate: optimist vs skeptic with moderator | `npx ts-node examples/agentic-workflows/multiagent-chat.ts` |
+| **[agents/01-basic-agent.ts](agents/01-basic-agent.ts)** | Simplest possible agent: define, run, print result | `npx tsx examples/agents/01-basic-agent.ts` |
+| **[agents/02-tools.ts](agents/02-tools.ts)** | LLM dynamically picks which tool to call | `npx tsx examples/agents/02-tools.ts` |
+| **[agents/03-multi-agent.ts](agents/03-multi-agent.ts)** | Multi-agent orchestration: sequential, parallel, handoffs | `npx tsx examples/agents/03-multi-agent.ts` |
+| **[agents/04-mcp-weather.ts](agents/04-mcp-weather.ts)** | MCP tool discovery + invocation for real-time data | `npx tsx examples/agents/04-mcp-weather.ts` |
+| **[agents/09-human-in-the-loop.ts](agents/09-human-in-the-loop.ts)** | Agent pauses for human approval mid-run | `npx tsx examples/agents/09-human-in-the-loop.ts` |
+| **[agents/15-agent-discussion.ts](agents/15-agent-discussion.ts)** | Multi-turn debate between agents with opposing viewpoints | `npx tsx examples/agents/15-agent-discussion.ts` |
 
 ### Monitoring
 
@@ -302,9 +306,9 @@ npx ts-node examples/advanced/sub-workflows.ts
 npx ts-node examples/api-journeys/metadata.ts
 npx ts-node examples/api-journeys/authorization.ts
 
-# 9. AI/LLM workflows (requires LLM integration)
-npx ts-node examples/agentic-workflows/function-calling.ts
-npx ts-node examples/agentic-workflows/multiagent-chat.ts
+# 9. Durable AI agents (requires an LLM API key — see agents/README.md)
+npx tsx examples/agents/01-basic-agent.ts
+npx tsx examples/agents/02-tools.ts
 ```
 
 ---
@@ -327,12 +331,7 @@ examples/
 ├── metrics.ts                       # Prometheus metrics + HTTP server
 ├── express-worker-service.ts        # Express.js + workers integration
 │
-├── agentic-workflows/               # AI/LLM agent examples
-│   ├── llm-chat.ts                  # Multi-turn automated AI conversation
-│   ├── llm-chat-human-in-loop.ts    # Interactive chat with WAIT pauses
-│   ├── function-calling.ts          # LLM-driven function routing
-│   ├── mcp-weather-agent.ts         # MCP tool discovery + invocation
-│   └── multiagent-chat.ts           # Multi-agent debate with moderator
+├── agents/                          # 200+ durable AI agent examples (see agents/README.md)
 │
 ├── api-journeys/                    # Complete API lifecycle demos
 │   ├── authorization.ts             # Users, groups, permissions (17 calls)