Align Python SDK documentation with the Java SDK’s documentation structure and Conductor-agent terminology. - #441
Merged
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
kowser-orkes
approved these changes
Jul 23, 2026
This was referenced Jul 28, 2026
ambiorix2099
added a commit
to conductor-oss/javascript-sdk
that referenced
this pull request
Jul 29, 2026
The agent layer was merged in from the Agentspan TS SDK, which has since been rebranded to Conductor. This aligns the naming with the Python and Java SDKs (conductor-oss/python-sdk#441 did the same). Renamed: - AGENTSPAN_* env vars -> CONDUCTOR_AGENT_* (18 distinct names, 189 files) - AgentspanError -> ConductorAgentError (base of 12 subclasses) - AgentspanMetadata -> ConductorAgentMetadata (langchain/langgraph wrappers) - Stripped 15 "Copyright (c) 2025 Agentspan" headers, as Python did Backward compatibility (the PR description upstream claims env aliases were kept; they were not -- Python deleted every AGENTSPAN_* read. We keep them): - AGENTSPAN_* still resolves as a deprecated fallback beneath CONDUCTOR_AGENT_*, warning once per name per process - AgentspanError / AgentspanMetadata stay exported as @deprecated aliases. The error alias is the same class object, not a subclass, so instanceof works in both directions - AGENTSPAN_LOG_LEVEL falls back silently: warning there would log through the very logger whose level is still being resolved - e2e/helpers.ts carries its own fallback -- that suite ships as a release bundle, and the SDK-level alias does not cover vars the harness reads directly Spec R3 precedence gains one tier and is otherwise unchanged: CONDUCTOR_* env -> explicit config -> CONDUCTOR_AGENT_* env -> AGENTSPAN_* env (deprecated) -> http://localhost:8080 Names deliberately left alone, because they are not ours to rename -- renaming them points users at flags that do not exist or breaks interop. Full table in AGENTS.md: - cross-SDK wire keys, all underscore-prefixed: __agentspan_ctx__, __agentspan_sdk__.cjs, _agentspan.llm/.model/.framework/.tools, _agentspan_human_task/_prompt. Same server compile path as Python. - orkes-conductor boot properties: agentspan.embedded, agentspan.default-context-window - external repos, scopes, images: agentspan-ai/agentspan, agentspan-ai/codingexamples, @agentspan-ai, agentspan-server - the external CLI: the `agentspan` binary, ~/.agentspan/config.json, agentspan_linux_amd64, and agentspan deploy/credentials/login/import - version-qualified product references: agentspan <= 0.4.2, agentspan server > 0.4.2 -- renaming these makes them factually false - CHANGELOG.md history, which records what shipped under the old names Tests: adds src/agents/__tests__/legacy-env.test.ts and four spec R3 cases covering the fallback, precedence, warn-once behaviour, and alias identity. The rest of the suite was mechanically renamed, so without these the compat guarantee would have no coverage at all. Verified: 0 lint errors (358 warnings, unchanged from main), 1582 unit tests across 80 suites pass, build + verify:dist clean, and zero net new tsc errors against main. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ambiorix2099
added a commit
to conductor-oss/javascript-sdk
that referenced
this pull request
Jul 29, 2026
Ports the layout established in conductor-oss/java-sdk and adopted by conductor-oss/python-sdk#441: docs/*.md plus docs/agents/{concepts,frameworks,reference}/. The 43 canonical pages are authored for TypeScript, not translated. The Python originals are Python prose with Python samples, so nothing was copyable -- every snippet here is TS against this SDK's actual API, mined from the six docs/agents pages being replaced. Authored (43): - docs/README.md index, organized by goal - 20 core guides server-setup, connection-authentication, core-quickstart, workflows, workflow-lifecycle, workers, reliability, observability, api-map, security, debugging, deployment-scaling, schedules-events, schema-client, workflow-testing, compatibility, upgrading, examples, documentation-standard, documentation-parity - docs/agents/concepts/ (11) agents, tools, multi-agent, guardrails, termination, callbacks, streaming-hitl, structured-output, scheduling, stateful, deploy-serve-run - docs/agents/frameworks/ (5) openai, google-adk, langchain, langgraph, vercel-ai - docs/agents/reference/ (6) api, runtime, client, agent-definition, agent-schema.md, agent-schema.json frameworks/ deviates from the canonical set deliberately: drops claude-agent-sdk (no such wrapper here) and adds vercel-ai, which is a JavaScript-only bridge with no Java or Python counterpart. Recorded in documentation-parity.md. Follows Python's documentation-standard verbatim -- "Conductor agents" as the noun, "Conductor-agent" hyphenated only attributively, an Audience line and Prerequisites on every page, goal/guide/result tables -- so the three sets stay diffable. agent-schema.json is a real draft-07 contract, not a placeholder: it validates all 19 fixtures in e2e/_configs/ (checked in the next commit's CI job). Stubs, not deletions (19), so inbound links from npm, issues, and blog posts keep resolving: - docs/agents/{getting-started,writing-agents,advanced,api-reference, framework-agents}.md -> their split replacements - docs/api-reference/*.md (11) -> api-map.md - METRICS.md -> docs/observability.md - LEASE_EXTENSION.md -> docs/reliability.md Java's CI greps to reject docs/agents/api-reference.md as retired while Python keeps it as a stub. We follow Python -- preserving inbound links to a public SDK's docs wins -- so the next commit's grep omits that pattern. METRICS.md and LEASE_EXTENSION.md content was migrated in full before stubbing (metric catalogs, labels, implementation notes, LeaseTracker usage, Python parity table), and their nine inbound references across README/SDK_DEVELOPMENT/SDK_NEW_LANGUAGE_GUIDE/SDK_COMPARISON/ WORKER_ARCHITECTURE_COMPARISON were repointed. CHANGELOG references were left alone -- it records what shipped under the old paths. Also fixes five pre-existing broken links in README.md, which pointed at docs/api-reference/{authorization,secret,prompt,integration,schema}-client.md -- files that never existed. They would have failed the link check added in the next commit. AGENTS.md's Documentation Maintenance contract now points at docs/observability.md, and gains a note that the stubs are deliberate. Verified: all 487 internal markdown links resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align Python SDK documentation with the Java SDK’s documentation structure and Conductor-agent terminology.