docs and clean up

Author: v1r3n

.github/workflows/pull_request.yml

@@ -32,7 +32,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e .
-          pip install pytest pytest-cov coverage
+          pip install pytest pytest-cov coverage jsonschema
 
       - name: Verify agents import without extras installed
         id: agent_base_import

.gitignore

@@ -173,3 +173,4 @@ tests/unit/automator/_trial_temp/_trial_marker
 
 # agent e2e bundle staging output (scripts/package-e2e-bundle.sh)
 scripts/e2e-bundle-dist/
+/design/openspec

README.md

@@ -192,7 +192,7 @@ The exact semantics of the runtime verbs. Implementations must match this table:
 
 ### `run` — start, wait, return the result
 `run(agent, prompt, *, version?, media?, session_id?, idempotency_key?, on_event?, timeout?, credentials?, context?, run_settings?) -> AgentResult`
-Serializes the agent (+ `run_settings` overrides), calls `start_agent`, starts the required tool workers, then polls status to a terminal state. Returns the rich result — the output is `result.output`, **not** a bare value. `credentials=[names]` asks the server to resolve those secrets for this run.
+Serializes the agent (+ `run_settings` overrides), calls `start_agent`, starts the required tool workers, then polls status to a terminal state. Returns the rich result — the output is `result.output`, **not** a bare value. Credential names configure worker `TaskDef.runtimeMetadata` locally and are not sent as workflow input.
 
 ### `start` — fire-and-forget
 `start(agent, prompt, *, version?, media?, session_id?, idempotency_key?, context?, run_settings?) -> AgentHandle`
@@ -212,7 +212,7 @@ Per agent: (1) **deploy it to the server** (same helper `deploy` uses — new on
 config_json = serialize(agent)
 if run_settings: config_json.update(run_settings.to_config_overrides())
 payload = {agentConfig: config_json, prompt, sessionId: session_id ?? "", media: media ?? []}
-+ optional keys only when set: context, idempotencyKey, timeoutSeconds, credentials, runId, static_plan
++ optional keys only when set: context, idempotencyKey, timeoutSeconds, runId, static_plan
 data = agent_client.start_agent(payload)
 execution_id, required_workers = data.executionId, data.requiredWorkers?
 prepare_workers(agent, required_workers)     # WorkerManager start — serve the tools

SDK_UPDATE_v1.md

@@ -0,0 +1,36 @@
+# Python SDK documentation
+
+Build durable workflow workers and Conductor agents with Python. These guides
+cover OSS and Orkes; pages call out capabilities that require Orkes.
+
+## Start here
+
+| Goal | Guide | Expected result |
+|---|---|---|
+| Connect to a server | [Server setup](server-setup.md) and [connection/authentication](connection-authentication.md) | The SDK can reach an OSS or Orkes API endpoint. |
+| Build a workflow and worker | [Core quickstart](core-quickstart.md) | The hello-world workflow prints its result. |
+| Build a Conductor agent | [Agent quickstart](agents/getting-started.md) | An LLM-backed agent completes through Conductor. |
+
+## Build
+
+- [Workflows](workflows.md), [workflow lifecycle](workflow-lifecycle.md), and [workers](workers.md)
+- [Workflow testing](workflow-testing.md), [schemas](schema-client.md), and [schedules/events](schedules-events.md)
+- [Conductor agents](agents/README.md), [tools](agents/concepts/tools.md), and [framework bridges](agents/README.md#framework-bridges)
+- [Recommended examples](examples.md); [examples/README.md](../examples/README.md) is the full catalog.
+
+## Operate
+
+- [Reliability](reliability.md), [security](security.md), and [deployment/scaling](deployment-scaling.md)
+- [Metrics and logging](observability.md) and [debugging](debugging.md)
+
+## Reference and upgrades
+
+- [Core API map](api-map.md), [compatibility](compatibility.md), and [upgrading](upgrading.md)
+- [Agent runtime](agents/reference/runtime.md), [control plane](agents/reference/client.md), and [agent definition](agents/reference/agent-definition.md)
+- [Java/Python documentation parity](documentation-parity.md) — intentional Python mappings and unsupported Java-only surfaces.
+
+## Documentation conventions
+
+Primary guides follow the [documentation standard](documentation-standard.md).
+Provider credentials belong on the Conductor server or its secret provider, not
+in workflow input, example source, or a client-side `.env` committed to Git.

docs/README.md

@@ -1,39 +1,46 @@
 # 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.
+Build durable Python AI agents on Conductor. Agents can use local Python tools,
+wait for people, execute dynamic plans, and recover after process restarts because
+Conductor persists execution state.
 
-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.
+## Install
 
-```python
-from conductor.ai.agents import Agent, AgentRuntime
+```shell
+pip install 'conductor-python[agents]'
+```
 
-agent = Agent(name="greeter", model="anthropic/claude-sonnet-4-6",
-              instructions="You are a friendly assistant.")
+Requirements: Python 3.10+ and a Conductor server with an LLM provider configured
+server-side. Replace example model names with a model enabled on that server.
 
-with AgentRuntime() as runtime:
-    result = runtime.run(agent, "Say hello.")
-    print(result.output)
-```
+## Start here
 
-## Docs
+- [Getting started](getting-started.md) — configure a server and run a basic agent.
+- [Deploy · Serve · Run · Plan](concepts/deploy-serve-run.md) — choose a runtime mode.
+- [Scheduling](concepts/scheduling.md) — manage deployed-agent schedules.
 
-- [Getting started](getting-started.md) — install, env vars, and a running agent in under 30 seconds.
-- [Writing agents](writing-agents.md) — the `Agent` class and `@agent`, tools, multi-agent strategies, handoffs, guardrails, termination, callbacks, streaming + HITL, schedules, stateful and instance agents.
-- [Framework agents](framework-agents.md) — run agents authored in the OpenAI Agents SDK, LangChain, LangGraph, or the Claude Agent SDK.
-- [Advanced](advanced.md) — runtime config, the control-plane `AgentClient`, deploy vs serve vs run vs plan, structured output, credentials, plans (`PLAN_EXECUTE`), skills.
-- [API reference](api-reference.md) — the public API surface in one place.
+## Build agents
 
-## Import surface
+- [Agents](concepts/agents.md), [tools](concepts/tools.md), and [multi-agent](concepts/multi-agent.md)
+- [Guardrails](concepts/guardrails.md), [termination](concepts/termination.md), [callbacks](concepts/callbacks.md)
+- [Stateful agents](concepts/stateful.md), [streaming and HITL](concepts/streaming-hitl.md), and [structured output](concepts/structured-output.md)
 
-Everything public is importable from `conductor.ai.agents`:
+## Framework bridges
 
-```python
-from conductor.ai.agents import Agent, AgentRuntime, tool, agent
-```
+- [Google ADK](frameworks/google-adk.md), [LangChain](frameworks/langchain.md), and [LangGraph](frameworks/langgraph.md)
+- [OpenAI Agents SDK](frameworks/openai.md) and [Claude Agent SDK](frameworks/claude-agent-sdk.md)
 
-A small OpenAI-Agents-compatible shim is also exposed at the top level:
+## Operate and inspect
 
-```python
-from conductor.ai import Runner, function_tool   # drop-in for `agents.Runner`
-```
+- [Runtime reference](reference/runtime.md), [control-plane reference](reference/client.md), and [API map](reference/api.md)
+- [Agent-definition fields](reference/agent-definition.md) and [configuration contract](reference/agent-schema.md)
+
+## What Conductor adds
+
+| Capability | Conductor agent runtime |
+|---|---|
+| Process recovery | Durable workflow state resumes from completed work. |
+| Python tools | Tools run as independently scalable Conductor worker tasks. |
+| Long-running work | Human approval, schedules, and events do not occupy application threads. |
+| Dynamic execution | Plans become durable, inspectable sub-workflows. |
+| Observability | Inputs, outputs, tool calls, retries, and status share one execution record. |