further updates

Author: v1r3n

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

@@ -306,7 +306,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 +494,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 |

LEASE_EXTENSION.md docs/LEASE_EXTENSION.mdLEASE_EXTENSION.md renamed to docs/LEASE_EXTENSION.md

@@ -128,7 +128,7 @@ If a heartbeat API call fails, the SDK retries up to 3 times with backoff (`1s`,
 
 ## Example
 
-See [examples/lease_extension_example.py](examples/lease_extension_example.py) for a complete runnable example that:
+See [examples/lease_extension_example.py](../examples/lease_extension_example.py) for a complete runnable example that:
 - Defines a long-running worker with `lease_extend_enabled=True`
 - Creates a workflow with a short `responseTimeoutSeconds`
 - Runs the workflow and proves the task completes despite sleeping longer than the timeout

docs/WORKER.md

@@ -610,7 +610,7 @@ class SimpleCppWorker(WorkerInterface):
 
 ## Long-Running Tasks and Lease Extension
 
-For tasks that take longer than the configured `responseTimeoutSeconds`, the SDK provides automatic lease extension to prevent timeouts. See the comprehensive [Lease Extension Guide](../LEASE_EXTENSION.md) for:
+For tasks that take longer than the configured `responseTimeoutSeconds`, the SDK provides automatic lease extension to prevent timeouts. See the comprehensive [Lease Extension Guide](LEASE_EXTENSION.md) for:
 
 - How lease extension works
 - Automatic vs manual control

docs/agents/README.md

@@ -1,9 +1,9 @@
-# Agentspan Python SDK
+# Conductor Agent Python SDK
 
 > Ships as part of [`conductor-python`](https://pypi.org/project/conductor-python/) — install with the `agents` extra
 > (`pip install 'conductor-python[agents]'`) — you're in the right place.
 
-Long-running, dynamic plan-execute, and event-driven AI agents in Python. You write plain Python; Agentspan compiles your agent into a Conductor workflow that runs on a server — with automatic retries, durable state, human-in-the-loop pauses, streaming, scheduling, dynamic plan-execute, and full execution history.
+Long-running, dynamic plan-execute, and event-driven AI agents in Python. You write plain Python; Conductor Agent compiles your agent into a Conductor workflow that runs on a server — with automatic retries, durable state, human-in-the-loop pauses, streaming, scheduling, dynamic plan-execute, and full execution history.
 
 ```python
 from conductor.ai.agents import Agent, AgentRuntime

docs/agents/advanced.md

@@ -47,8 +47,10 @@ For one-off scripts, top-level functions use a shared singleton runtime:
 
 ```python
 import conductor.ai.agents as ag
+from conductor.client.configuration.configuration import Configuration
 
-ag.configure(server_url="https://prod:8080/api")  # before first run
+# Connection/auth via a Configuration; agent-behaviour knobs via config=AgentConfig(...).
+ag.configure(configuration=Configuration(server_api_url="https://prod:8080/api"))  # before first run
 result = ag.run(agent, "Hello!")
 ag.shutdown()    # explicit cleanup; not required for simple scripts
 ```
@@ -64,13 +66,16 @@ ag.shutdown()    # explicit cleanup; not required for simple scripts
 | `runtime.run(agent, prompt)` | yes | `AgentResult` | Simplest case — run and get the answer |
 | `runtime.start(agent, prompt)` | no | `AgentHandle` | Fire-and-forget; poll/control later |
 | `runtime.stream(agent, prompt)` | iterates | `AgentStream` | Watch events live; drive HITL |
-| `runtime.deploy(*agents)` | yes | `list[DeploymentInfo]` | CI/CD: compile + register, no execution |
-| `runtime.serve(*agents)` | yes (blocks) | — | Long-lived worker process; polls until interrupted |
+| `runtime.deploy(*agents)` | yes | `list[DeploymentInfo]` | CI/CD: compile + register, no workers, no execution |
+| `runtime.serve(*agents)` | yes (blocks) | — | Register agent(s) **and** serve workers; long-lived, polls until interrupted (`serve` = `deploy` + serve) |
 | `runtime.plan(agent)` | yes | `dict` | Compile to a workflow def without running anything |
 
 `run`/`start`/`stream` accept `media=`, `session_id=`, `idempotency_key=`,
 `credentials=`, and extra `**kwargs` as workflow input. `run`/`run_async` also accept
 `on_event=` to stream while running synchronously, `timeout=`, and `context=`.
+`run`/`start` (and their async variants) also accept `run_settings=` — a `RunSettings`
+(or dict) that overrides the agent's `model`/`temperature`/`max_tokens`/… for that one
+call. See [API reference](api-reference.md#per-run-overrides--runsettings).
 
 `plan(agent)` returns `{"workflowDef": ..., "requiredWorkers": ...}` — useful to
 inspect the compiled Conductor workflow:
@@ -91,9 +96,13 @@ runtime.deploy(agent)
 #   agentspan deploy --path ./agents --agents greeter,support
 
 # Long-lived worker process:
-runtime.serve(agent)        # blocks, polling for tool tasks
+runtime.serve(agent)        # registers the agent (idempotent) + blocks, polling for tool tasks
 ```
 
+`serve` also registers the agent on the server, so the explicit `deploy` step above
+is optional — it's still useful to register/upgrade the workflow from CI independently
+of the worker rollout.
+
 `resume(execution_id, agent)` re-attaches to a previously `start`ed execution and
 re-registers its tool workers (e.g. after a process restart):
 

docs/agents/api-reference.md

@@ -29,15 +29,15 @@ Context manager (sync and async: `with` / `async with`).
 
 | Method | Signature | Purpose |
 |---|---|---|
-| `run` | `(agent, prompt=None, *, version=None, media=None, session_id=None, idempotency_key=None, on_event=None, timeout=None, credentials=None, context=None, **kwargs) -> AgentResult` | Run synchronously |
+| `run` | `(agent, prompt=None, *, version=None, media=None, session_id=None, idempotency_key=None, on_event=None, timeout=None, credentials=None, context=None, run_settings=None, **kwargs) -> AgentResult` | Start, wait for completion, return the result (also starts workers) |
 | `run_async` | same as `run` | Async run |
-| `start` | `(agent, prompt=None, *, version=None, media=None, session_id=None, idempotency_key=None, context=None, **kwargs) -> AgentHandle` | Fire-and-forget |
+| `start` | `(agent, prompt=None, *, version=None, media=None, session_id=None, idempotency_key=None, context=None, run_settings=None, **kwargs) -> AgentHandle` | Fire-and-forget; returns a handle (also starts workers) |
 | `start_async` | same as `start` | Async start |
 | `stream` | `(agent=None, prompt=None, *, version=None, handle=None, media=None, session_id=None, **kwargs) -> AgentStream` | Stream events |
 | `stream_async` | same as `stream` | `-> AsyncAgentStream` |
-| `deploy` | `(*agents, packages=None, schedules=_UNSET) -> list[DeploymentInfo]` | Compile + register |
+| `deploy` | `(*agents, packages=None, schedules=_UNSET) -> list[DeploymentInfo]` | Compile + register agent(s) on the server; does **not** start workers |
 | `deploy_async` | same | Async deploy |
-| `serve` | `(*agents, packages=None, blocking=True) -> None` | Register + poll workers |
+| `serve` | `(*agents, packages=None, blocking=True) -> None` | Register agent(s) on the server **and** serve/poll their workers (`serve` = `deploy` + serve) |
 | `plan` | `(agent) -> dict` | Compile to workflow def |
 | `resume` | `(execution_id, agent, *, timeout=None) -> AgentHandle` | Re-attach + re-register workers |
 | `resume_async` | same | Async resume |
@@ -57,6 +57,28 @@ Async variants exist for status/respond/approve/reject/send/stop/shutdown
 `start`, `start_async`, `stream`, `stream_async`, `resume`, `resume_async`, `deploy`,
 `deploy_async`, `serve`, `plan`, `configure`, `shutdown`.
 
+### Per-run overrides — `RunSettings`
+
+`run` / `start` (and their async variants and the module-level wrappers) accept
+`run_settings=` to override an agent's LLM settings for a single invocation
+without rebuilding the `Agent`:
+
+```python
+from conductor.ai.agents import RunSettings
+
+runtime.run(
+    agent,
+    "Summarize this.",
+    run_settings=RunSettings(model="anthropic/claude-sonnet-4-6", temperature=0.0, max_tokens=512),
+)
+```
+
+`RunSettings(model=None, temperature=None, max_tokens=None, reasoning_effort=None,
+thinking_budget_tokens=None)` — only the fields you set override; unset fields keep
+the agent's own values (so `temperature=0.0` is honored). A plain `dict` with the
+same keys is also accepted. Overrides apply to the root agent's config; sub-agents
+keep their own settings.
+
 ## Agent
 
 `Agent(name, model="", instructions="", tools=None, agents=None,

docs/agents/framework-agents.md

@@ -1,7 +1,7 @@
 # Framework agents
 
-Agentspan can run agents authored in other frameworks by bridging them onto its
-durable runtime. You keep your framework's authoring API; Agentspan handles
+Conductor Agent can run agents authored in other frameworks by bridging them onto its
+durable runtime. You keep your framework's authoring API; Conductor Agent handles
 durability, retries, streaming, and observability.
 
 Supported bridges: **OpenAI Agents SDK**, **LangChain**, **LangGraph**, **Claude
@@ -21,7 +21,7 @@ SDK's `Runner` with a native `Agent`.
 ### Drop-in `Runner`
 
 Change one import — `from conductor.ai import Runner` instead of `from agents import
-Runner` — and run your existing OpenAI-Agents agent on Agentspan:
+Runner` — and run your existing OpenAI-Agents agent on Conductor Agent:
 
 ```python
 from conductor.ai import Runner            # the one line that changes
@@ -86,7 +86,7 @@ with AgentRuntime() as runtime:
     result.print_result()
 ```
 
-Agentspan also provides a thin wrapper, `conductor.ai.agents.langchain.create_agent`,
+Conductor Agent also provides a thin wrapper, `conductor.ai.agents.langchain.create_agent`,
 that captures the model, tools, and system prompt up front so they compile to native
 server-side model + tool tasks (rather than running the whole agent in one opaque
 worker).
@@ -157,4 +157,4 @@ functions are not yet supported there.
 
 You can also bring `ClaudeCodeOptions` / a Claude Agent SDK agent directly; the bridge
 runs the full `query()` in one durable worker with instrumentation hooks that stream
-tool-use and lifecycle events back to Agentspan.
+tool-use and lifecycle events back to Conductor Agent.

docs/agents/getting-started.md

@@ -11,7 +11,7 @@ pip install 'conductor-python[agents]'
 Or, per framework, install just what you need — e.g. `conductor-python[langchain]`,
 `conductor-python[adk]`, `conductor-python[claude]`.
 
-Point the SDK at a running Agentspan server (defaults to `http://localhost:8080/api`):
+Point the SDK at a running Conductor Agent server (defaults to `http://localhost:8080/api`):
 
 ```bash
 export AGENTSPAN_SERVER_URL=http://localhost:8080/api