{
  "markdown": "# Sapiom SDK\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)\n\n> ⚠️ **Beta Status:** Currently in v0.x (beta). API may change before v1.0.0.\n> Production-ready and actively maintained.\n\nTypeScript SDK for **building, running, and operating AI agents on Sapiom**.\nAuthor agents as typed step graphs, call Sapiom paid tools (sandboxes, git\nrepos, coding models, search, file storage, …) directly from your code, and ship\nthem to the Sapiom engine from the CLI, your coding agent's MCP, or the\n**Sapiom Studio** desktop app.\n\n## 📦 Packages\n\nThis is a monorepo of focused packages. Install only what you need.\n\n### Build & run agents\n\n| Package                           | Version                                                                                           | Description                                                                                     |\n| --------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |\n| [@sapiom/agent](./packages/agent) | [![npm](https://img.shields.io/npm/v/@sapiom/agent)](https://www.npmjs.com/package/@sapiom/agent) | The authoring contract: `defineAgent`, `defineStep`, directives (`goto`/`terminate`), and types |\n| [@sapiom/tools](./packages/tools) | [![npm](https://img.shields.io/npm/v/@sapiom/tools)](https://www.npmjs.com/package/@sapiom/tools) | Typed client for Sapiom capabilities — the same tools your agents call, callable from your code |\n| [@sapiom/cli](./packages/cli)     | [![npm](https://img.shields.io/npm/v/@sapiom/cli)](https://www.npmjs.com/package/@sapiom/cli)     | Command line: scaffold, validate, deploy, and schedule agents                                   |\n| [@sapiom/mcp](./packages/mcp)     | [![npm](https://img.shields.io/npm/v/@sapiom/mcp)](https://www.npmjs.com/package/@sapiom/mcp)     | Local developer MCP server (`sapiom-dev`) — build & operate agents from your coding agent       |\n\n### Agent Studio\n\nAgent Studio runs your coding agent (Claude Code or Codex) in a\nSapiom-configured environment: MCP pre-wired, agent projects tracked, one-click\ndeploy/run, and a live canvas for previews.\n\n| Package                                             | Version                                                                                                             | Description                                                                                     |\n| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| [@sapiom/agent-studio](./packages/agent-studio)     | [![npm](https://img.shields.io/npm/v/@sapiom/agent-studio)](https://www.npmjs.com/package/@sapiom/agent-studio)     | Agent Studio launcher — `npx @sapiom/agent-studio@latest`                                       |\n| [@sapiom/harness](./packages/harness)               | [![npm](https://img.shields.io/npm/v/@sapiom/harness)](https://www.npmjs.com/package/@sapiom/harness)               | The Agent Studio implementation — a CLI-launched local web app                                  |\n| [@sapiom/harness-desktop](./packages/harness-desktop) | [![GitHub release](https://img.shields.io/github/v/release/sapiom/sapiom-js?filter=v*)](https://github.com/sapiom/sapiom-js/releases) | **Sapiom Studio** desktop app (Electron) — ships as signed installers, not to npm               |\n\n### Runtime internals\n\nLower-level packages that power the stack above. Most users never import these\ndirectly, but they're published for advanced/host integrations.\n\n| Package                                           | Version                                                                                                           | Description                                                                                             |\n| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| [@sapiom/agent-core](./packages/agent-core)       | [![npm](https://img.shields.io/npm/v/@sapiom/agent-core)](https://www.npmjs.com/package/@sapiom/agent-core)       | Pure, stateless functions for scaffolding, validating, and operating agents — shared by the CLI and MCP |\n| [@sapiom/agent-runtime](./packages/agent-runtime) | [![npm](https://img.shields.io/npm/v/@sapiom/agent-runtime)](https://www.npmjs.com/package/@sapiom/agent-runtime) | Host-agnostic graph-walker runtime — one runtime, two hosts (server engine + local runner)              |\n\n## 🚀 Quick Start\n\n**New to Sapiom?** The fastest path is the CLI or the developer MCP — both\nscaffold a working agent for you. See the [examples folder](./examples) for\ncomplete, runnable projects.\n\n### Scaffold an agent with the CLI\n\n```bash\nnpx @sapiom/cli agents init my-app   # scaffold a project\ncd my-app\nnpx @sapiom/cli agents check         # validate locally (bundle, manifest, graph)\nnpx @sapiom/cli agents deploy        # build and ship\n```\n\n### Build with your coding agent in Agent Studio\n\nOne command checks your environment, signs you in, and opens Agent Studio with\nyour coding agent running in an embedded terminal:\n\n```bash\nnpx @sapiom/agent-studio@latest [dir]\n```\n\nPrefer a native app? **Sapiom Studio** is the one-click desktop host for the\nsame experience — download installers (macOS, Windows, Linux) from\n[GitHub Releases](https://github.com/sapiom/sapiom-js/releases).\n\n### Author an agent\n\nAn agent is a typed graph of steps. Each step does work and returns a directive\ntelling the runtime where to go next.\n\n```typescript\nimport { defineAgent, defineStep, goto, terminate } from \"@sapiom/agent\";\n\nconst start = defineStep({\n  name: \"start\",\n  next: [\"finish\"],\n  async run(input, ctx) {\n    return goto(\"finish\", { greeting: `hello ${input.name}` });\n  },\n});\n\nconst finish = defineStep({\n  name: \"finish\",\n  next: [],\n  terminal: true,\n  async run(input) {\n    return terminate({ done: true, ...input });\n  },\n});\n\nexport const hello = defineAgent({\n  name: \"hello\",\n  entry: \"start\",\n  steps: { start, finish },\n});\n```\n\n### Call Sapiom capabilities from your code\n\n`@sapiom/tools` exposes the same capabilities your agents call as tools, typed\nand authenticated to your tenant.\n\n```typescript\nimport { createClient } from \"@sapiom/tools\";\n\nconst sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });\n\n// Create a repo, have a coding model build into it, then publish.\nconst repo = await sapiom.repositories.create(\"landing-page\");\nconst run = await sapiom.models.coding.run({\n  task: \"Build a one-page marketing site in index.html.\",\n  gitRepository: repo,\n});\n\nif (run.result?.success) {\n  const { sha } = await repo.pushFromSandbox(run.sandbox, {\n    message: \"build: landing\",\n  });\n  console.log(\"published\", sha);\n}\n```\n\n### Build agents from your coding agent (MCP)\n\nAdd the local developer MCP so your coding agent can scaffold, test, deploy, and\ninspect Sapiom agents. In Claude Code:\n\n```sh\nclaude mcp add sapiom-dev -- npx -y @sapiom/mcp\n```\n\n> `@sapiom/mcp` is the **local developer** surface (`sapiom_dev_*`). It is\n> distinct from the remote Sapiom capability MCP that services paid tool calls —\n> see [docs/mcp-servers.md](./docs/mcp-servers.md) for which to use when.\n\n## 📚 Documentation\n\n- **[Examples](./examples/README.md)** — runnable example projects\n- **[The two Sapiom MCP servers](./docs/mcp-servers.md)** — local dev vs. remote capabilities\n- **[@sapiom/agent](./packages/agent/README.md)** — authoring contract\n- **[@sapiom/tools](./packages/tools/README.md)** — capability client\n- **[@sapiom/cli](./packages/cli/README.md)** — command line\n- **[@sapiom/mcp](./packages/mcp/README.md)** — developer MCP\n- **[Agent Studio](./packages/harness/README.md)** — local app for building with your coding agent\n\n## 🏗️ Package Architecture\n\n```\n@sapiom/agent            Authoring contract (defineAgent, directives, types)\n    ↑\n    ├── @sapiom/agent-runtime   Host-agnostic graph-walker runtime\n    └── @sapiom/agent-core      Scaffold / validate / operate (pure functions)\n            ↑\n            ├── @sapiom/cli     Command line\n            └── @sapiom/mcp     Local developer MCP (sapiom-dev)\n\n@sapiom/tools            Typed capability client (sandboxes, repos, models, …)\n\n@sapiom/harness          Agent Studio (local web app; launched via @sapiom/agent-studio)\n    ↑\n    └── @sapiom/harness-desktop   Sapiom Studio desktop app (Electron host, ships as installers)\n```\n\n## 🛠️ Development\n\nThis is a pnpm workspace monorepo.\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run tests\npnpm test\n\n# Lint and format\npnpm lint\npnpm format\n```\n\n### Package Scripts\n\n```bash\n# Build / test a specific package\npnpm --filter @sapiom/agent build\npnpm --filter @sapiom/tools test\n\n# Watch mode\npnpm --filter @sapiom/agent dev\n```\n\n### Publishing\n\nWe use [Changesets](https://github.com/changesets/changesets) for version management:\n\n```bash\npnpm changeset          # create a changeset\npnpm version-packages   # apply version bumps\npnpm release            # build and publish to npm\n```\n\n## 🤝 Contributing\n\nContributions welcome! Please read our [Contributing Guide](./CONTRIBUTING.md)\nfirst — it explains which changes can go straight to a pull request (focused\nbug fixes, documentation corrections, single-template additions) and which need\na maintainer-agreed [issue](https://github.com/sapiom/sapiom-js/issues) before\nyou invest in them (new features, public API changes, new dependencies,\ncross-package work).\n\nIn short:\n\n1. Fork the repository and branch from the latest `main`\n2. Keep the change focused on one problem, with tests for changed behavior\n3. Run the root checks (`pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm test`)\n4. Add a [changeset](./CONTRIBUTING.md#changesets) when a published package's behavior or API changes\n5. Open a pull request and complete every applicable section of the template\n\nAI-assisted contributions are welcome but must be disclosed, reviewed, and\nvalidated by the contributor. For suspected security vulnerabilities, follow\nthe [Security Policy](./SECURITY.md) instead of opening a public issue.\n\n## 📄 License\n\nMIT © [Sapiom](LICENSE)\n\n## 🔗 Links\n\n- [Website](https://sapiom.ai)\n- [Documentation](https://docs.sapiom.ai)\n- [NPM Organization](https://www.npmjs.com/org/sapiom)\n- [GitHub Issues](https://github.com/sapiom/sapiom-js/issues)\n",
  "bytes": 10946,
  "sha": "6f9482c49ac36e2a0e44a3584aa27c7eb5e97ca92766e21826c3eb95b1b964c0",
  "repo_slug": "sapiom/sapiom-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sapiom_mcp_c0f30c3e/readme"
}