feat: consolidate agent control-plane onto AgentClient; fix worker credential delivery (#421)

Author: v1r3n

.github/workflows/agent-e2e.yml

@@ -17,7 +17,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  AGENTSPAN_VERSION: "0.4.0"   # pinned server/CLI release — bump deliberately
+  AGENTSPAN_VERSION: "0.4.3"   # pinned server/CLI release — bump deliberately
 
 jobs:
   agent-e2e:

.gitignore

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Example-run artifacts (generated by run_all_examples.py / coding-agent examples)
+examples/agents/run_report.html
+examples/agents/codingexamples/
+
 # C extensions
 *.so
 

AGENTS.md AGENT.mdAGENTS.md renamed to AGENT.md

@@ -14,33 +14,33 @@ This guide provides a complete blueprint for creating or refactoring Conductor S
 
 ```
 ┌─────────────────────────────────────────────────┐
-│              Application Layer                   │
-│         (User's Application Code)                │
+│              Application Layer                  │
+│         (User's Application Code)               │
 └─────────────────────────────────────────────────┘
                        ↓
 ┌─────────────────────────────────────────────────┐
-│            High-Level Clients                    │
-│   (OrkesClients, WorkflowExecutor, Workers)      │
+│            High-Level Clients                   │
+│   (OrkesClients, WorkflowExecutor, Workers)     │
 └─────────────────────────────────────────────────┘
                        ↓
 ┌─────────────────────────────────────────────────┐
-│         Domain-Specific Clients                  │
-│  (TaskClient, WorkflowClient, SecretClient...)   │
+│         Domain-Specific Clients                 │
+│  (TaskClient, WorkflowClient, SecretClient...)  │
 └─────────────────────────────────────────────────┘
                        ↓
 ┌─────────────────────────────────────────────────┐
-│             Orkes Implementations                │
-│     (OrkesTaskClient, OrkesWorkflowClient...)    │
+│             Orkes Implementations               │
+│     (OrkesTaskClient, OrkesWorkflowClient...)   │
 └─────────────────────────────────────────────────┘
                        ↓
 ┌─────────────────────────────────────────────────┐
-│              Resource API Layer                  │
-│    (TaskResourceApi, WorkflowResourceApi...)     │
+│              Resource API Layer                 │
+│    (TaskResourceApi, WorkflowResourceApi...)    │
 └─────────────────────────────────────────────────┘
                        ↓
 ┌─────────────────────────────────────────────────┐
-│              HTTP/API Client                     │
-│         (ApiClient, HTTP Transport)              │
+│              HTTP/API Client                    │
+│         (ApiClient, HTTP Transport)             │
 └─────────────────────────────────────────────────┘
 ```
 
@@ -255,6 +255,84 @@ Abstract Interface (20+ methods):
 
 ---
 
+## 🤖 Agent SDK Layer
+
+An **optional higher-level layer** for building LLM agents on top of the client +
+worker SDK. Agents are authored in code but **compiled and executed on the server**
+as durable Conductor workflows; an agent's tools are ordinary Conductor **workers**
+(reuse the entire Worker Framework, Phase 3). Full language-agnostic spec:
+[`docs/design/WORKER_SDK_IMPLEMENTATION_GUIDE.md` §25](docs/design/WORKER_SDK_IMPLEMENTATION_GUIDE.md#25-agent-sdk-layer-building-agents-on-the-worker-sdk).
+
+### Two Planes
+
+```
+                    ┌───────────────────────────────┐
+                    │          AgentRuntime         │  (facade)
+                    └───────────────────────────────┘
+                     │                             │
+       control plane │                             │ worker plane
+                     ▼                             ▼
+         ┌───────────────────────┐   ┌────────────────────────────┐
+         │      AgentClient      │   │  WorkerManager/TaskHandler  │
+         │  /agent/* over the    │   │  (Phase 3 workers serve     │
+         │  standard ApiClient   │   │   the agent's tools)        │
+         └───────────────────────┘   └────────────────────────────┘
+```
+
+### Core Components
+
+| Component | Role |
+|---|---|
+| `AgentRuntime` | User-facing facade: `run`/`start`/`stream`/`deploy`/`serve`/`plan` (+ async). Composes a `Configuration`, `AgentConfig`, `AgentClient`, and a `WorkerManager`. |
+| `AgentClient` (interface) + `OrkesAgentClient` | Control plane (compile/deploy/start/status/stream/respond/stop/signal). Built on the **standard `ApiClient`** — reuses its token management; no separate token cache. Same interface + Orkes-impl pattern as the domain clients (Phase 2). |
+| `AgentConfig` | Agent-runtime **behaviour** only (worker pool, liveness, streaming, integration auto-register). Connection/auth/log level come from `Configuration`. |
+| `RunSettings` | Per-run LLM overrides (`model`/`temperature`/`max_tokens`/…) for a single `run`/`start`; applied to the serialized agent config before start. |
+| Framework adapters | Run agents authored in LangChain / LangGraph / OpenAI Agents SDK / Claude Agent SDK on the durable runtime as spawn-safe passthrough workers. |
+
+### Verb Contract
+
+| Method | Blocks | Returns | Starts workers | Registers on server |
+|---|---|---|---|---|
+| `run` | yes | result (output + ids) | yes | via start |
+| `start` | no | handle (`execution_id`) | yes | via start |
+| `deploy` | yes | deployment info | no | yes |
+| `serve` | yes (until signal) | — | yes | yes (`serve` = `deploy` + serve) |
+| `plan` | yes | workflow def | no | no |
+
+### Key Principles
+
+- **Single token authority** — control plane *and* worker-side agent posts reuse the one `ApiClient`'s mint/cache/TTL-refresh/401-retry; never a parallel token cache. In spawned workers, rebuild + cache a client per `(server_url, auth_key)`.
+- **Spawn-safety** — tool/worker callables must be module-level (importable/picklable), never `<locals>` closures; entry scripts use a main-module guard.
+- **Credentials** — declared per tool; the server resolves + delivers them on wire-only `Task.runtimeMetadata`; injected into the worker env for the call, never read from ambient env.
+- **Config single-source** — connection/auth/log level live on `Configuration`; `AgentConfig` is behaviour-only.
+
+### Package Additions
+
+```
+src/conductor/
+├── client/
+│   ├── agent_client.{ext}                 # AgentClient interface
+│   └── orkes/orkes_agent_client.{ext}     # OrkesAgentClient (on ApiClient)
+└── ai/agents/                             # agent authoring + runtime
+    ├── agent.{ext}, run_settings.{ext}
+    ├── runtime/ (runtime, config, worker_manager)
+    ├── _internal/agent_http.{ext}         # single token authority for /agent/* posts
+    └── frameworks/ (langchain, langgraph, claude_agent_sdk, …)
+```
+
+### Agent-Layer Checklist
+
+- [ ] `AgentClient` interface + Orkes impl on the standard `ApiClient` (sync + async; SSE reuses the client's auth header)
+- [ ] `AgentRuntime` facade with the exact verb contract above
+- [ ] `AgentConfig` behaviour-only; connection/auth/log level from `Configuration`
+- [ ] `RunSettings` per-run LLM overrides
+- [ ] Single token authority across control plane + worker-side posts
+- [ ] Tool workers reuse the Worker Framework (Phase 3); credentials via `runtimeMetadata`
+- [ ] Framework adapters as spawn-safe passthrough workers
+- [ ] Liveness monitor for stateful runs
+
+---
+
 ## 🌐 Language-Specific Implementation
 
 ### Java Implementation

README.md

@@ -34,9 +34,20 @@ If you find [Conductor](https://github.com/conductor-oss/conductor) useful, plea
 
 ## Start Conductor Server
 
-If you don't already have a Conductor server running, pick one:
+#### Conductor CLI
+```shell
+# Installs conductor cli
+npm install -g @conductor-oss/conductor-cli
+
+# Start the open source conductor server on port 8080
+conductor server start
+# see conductor server --help for all the available commands
+```
+
 
-**Docker Compose (recommended, includes UI):**
+Alternatively, if you want to use docker
+
+**Docker Compose**
 
 ```shell
 docker run -p 8080:8080 conductoross/conductor:latest
@@ -48,15 +59,6 @@ The UI will be available at `http://localhost:8080` and the API at `http://local
 curl -sSL https://raw.githubusercontent.com/conductor-oss/conductor/main/conductor_server.sh | sh
 ```
 
-**Conductor CLI**
-```shell
-# Installs conductor cli
-npm install -g @conductor-oss/conductor-cli
-
-# Start the open source conductor server
-conductor server start
-# see conductor server --help for all the available commands
-```
 
 ## Install the SDK
 
@@ -306,7 +308,7 @@ def train_model(dataset_id: str) -> dict:
     return {'model_id': model.id, 'accuracy': model.accuracy}
 ```
 
-Disabled by default. Enable per-worker via decorator, constructor, or environment variable (`conductor_worker_<task>_lease_extend_enabled=true`). See [LEASE_EXTENSION.md](LEASE_EXTENSION.md) for the full guide.
+Disabled by default. Enable per-worker via decorator, constructor, or environment variable (`conductor_worker_<task>_lease_extend_enabled=true`). See [LEASE_EXTENSION.md](docs/LEASE_EXTENSION.md) for the full guide.
 
 ### Monitoring with Metrics
 
@@ -494,7 +496,7 @@ End-to-end examples covering all APIs for each domain:
 | [Worker Design](docs/design/WORKER_DESIGN.md) | Architecture: AsyncTaskRunner vs TaskRunner, discovery, lifecycle |
 | [Worker Guide](docs/WORKER.md) | All worker patterns (function, class, annotation, async) |
 | [Worker Configuration](WORKER_CONFIGURATION.md) | Hierarchical environment variable configuration |
-| [Lease Extension](LEASE_EXTENSION.md) | Automatic heartbeat for long-running tasks |
+| [Lease Extension](docs/LEASE_EXTENSION.md) | Automatic heartbeat for long-running tasks |
 | [Workflow Management](docs/WORKFLOW.md) | Start, pause, resume, terminate, retry, search |
 | [Workflow Testing](docs/WORKFLOW_TESTING.md) | Unit testing with mock outputs |
 | [Task Management](docs/TASK_MANAGEMENT.md) | Task operations |