Agents and agent projects
A Sapiom agent is a controlled, multi-step automation. Its code declares an entry step, the steps it can run, and the transitions between them. A step can call Sapiom capabilities through ctx.sapiom and returns a directive that tells the runtime where to go next.
An agent project is the local source folder used to build that agent. It contains the TypeScript definition, package files, local capability stubs, and—once created by the authoring tools—sapiom.json.
What sapiom.json does
Section titled “What sapiom.json does”Agent Studio recognizes an agent project by its sapiom.json file. The file records team-shared project identity and provenance, including which hosted agent the project is linked to. It is a re-resolvable cache; Sapiom’s server remains the source of truth.
sapiom.json is not the agent’s source code, a deployment manifest, or a credential store. It never contains your Sapiom API key. Let Agent Studio or the authoring tools create and update it instead of hand-editing server IDs.
A new source folder can exist before sapiom.json does. Studio treats that as a workspace where a coding agent can scaffold an agent project. Once the marker exists, Studio can discover the project and show it as an agent in the workspace rail.
Local project and hosted agent
Section titled “Local project and hosted agent”The local project and the hosted agent are related, but they are not the same object:
| Term | Meaning |
|---|---|
| Agent project | The source folder on your machine. |
| Hosted agent | The organization-owned cloud record linked to the project. API fields call this a definition. |
| Deploy | The action that submits an exact source revision and starts an asynchronous build. |
| Version | A source revision in the hosted agent’s version history. Only a revision backed by a ready build is runnable; unbuilt and failed revisions can also appear. |
| Active version | The ready version a new production run will use: an explicit pin when present, otherwise the latest ready build. |
| Run | One invocation of an agent. API fields and tools may call it an execution and return an executionId. |
Linking associates a local project with a hosted agent; it does not prove that a runnable version exists. Deploying starts a build. A production run can start only after the hosted agent has a ready version.
Each production run keeps the version it started with. Deploying a newer revision changes what future runs resolve, not the code already pinned to an in-progress or completed run.
Public and implementation terms
Section titled “Public and implementation terms”Product pages use agent, version, and run. You will still encounter the compatibility terms workflow, definition, and execution in API routes, tool names, and response fields. They refer to the same cloud model at a lower level; use the literal names only when you are working with that interface.
Next, learn how workspaces and sessions organize local work, or read the agent authoring guide.
© 2026 Sapiom, Inc.