Sourced*

Agent playbooks

Agent playbook: OpenAPI to SDK packages and docs

· 2 min read · Sourced

  • agents
  • openapi
  • sdks
  • npm
  • pypi

If a user gives an agent an OpenAPI file and says "make SDKs and docs," the agent should avoid the trap of generating code only. A real API launch needs packages, docs, examples, agent-readable files, release checks, and approval gates.

Step 1: validate the spec

Check:

  • OpenAPI version is 3.0.x or 3.1.x.
  • info.title and info.version exist.
  • Every operation has an operationId.
  • Auth is defined under components.securitySchemes.
  • Responses include real schemas and examples.
  • Path parameters are declared.

If this fails, use the OpenAPI validator before generating anything.

Step 2: package targets

Ask or infer:

  • npm package name.
  • PyPI package name.
  • TypeScript import path.
  • Python import module.
  • Auth environment variable.
  • README example endpoint.

Do not invent package names if there is an existing package.

Step 3: generate previews

Manual path:

  1. Generate TypeScript package.
  2. Run tsc --noEmit, build, npm pack, and tarball install.
  3. Generate Python package.
  4. Run compileall, wheel build, and wheel install.
  5. Generate docs from OpenAPI.
  6. Write llms.txt, skill file, and MCP server manually or with separate tools.

Sourced path:

  1. Upload OpenAPI.
  2. Review TypeScript and Python client package artifacts.
  3. Review docs preview.
  4. Review skill-file draft.
  5. Review MCP server bundle.
  6. Review npm and PyPI readiness.
  7. Download artifacts and run local smoke checks if the user wants repo-level proof.
  8. Stop before publish/cutover unless the user approves the exact package, version, repo, and docs target.

Step 4: do not publish by accident

Publishing is a separate human-approved action. Previewing is safe. Dry-runs never publish packages or cut over docs, but they may read registry metadata and, when configured, dispatch non-publishing smoke-check CI. Real writes to npm, PyPI, GitHub, or docs DNS are not safe unless the user explicitly asks for that exact release.

Treat trusted publishing/OIDC as the preferred long-term registry path. Trusted publishing means a registry-trusted GitHub Actions workflow/OIDC publisher configured for the package or project. Do not paste long-lived npm or PyPI tokens into generated projects or chat logs. If the registry connection is missing, report the missing repo, workflow, or registry configuration and keep the run in preview/dry-run mode.

Agent output format

Return a compact report:

OpenAPI status:
Package targets:
Generated artifacts:
Smoke checks:
Docs preview:
Skill file:
MCP server:
Registry readiness:
Required approvals:

Sourced advantage

Sourced keeps these artifacts tied to one OpenAPI source. Agents can inspect the same run for docs, packages, skill files, MCP, and release readiness instead of reconciling five independent tools.