Workspace apps SDK
Directory: sdk/appsdk
Source docs/en/site/sdk-appsdk.md
Directory: sdk/appsdk Who this is for: people who should finish this directory and then be able to hand-build a lightweight workspace app (UI description + in-pack scripts + optional data pipeline).
Suggested reading order
- Hand-build an app — overall path and checklists (get the big picture first)
- App UI description — hand-write
app.json(entities / views / actions) - App views — why there are only three views; what to do from a design or screenshot
- App package layout — what the directory must contain, what invoke copies
- App actions — how to write
handlers.pyafter the UI gains a feature - App data pipeline —
pipeline.json, platform bridge, assembling reports - App assistant brief — standing rules for the app-development assistant / create wizard (kept in sync with the embedded copy)
Mechanism overview (HTTP / create from conversation): Workspace apps.
Document index
| Document | Contents |
|---|---|
| Hand-build an app | From-scratch paths A/B, acceptance checklist |
| App UI description | Full app.json fields and validation |
| App views | Three views, no layout model, how to extend, UI from a picture |
| App package layout | Pack file tree, required/optional, sandbox copy scope |
| App actions | handle contract, platform bridge, steps to add an action |
| App data pipeline | pipeline, orchestration and assemble, alignment with data connections |
| App assistant brief | Runtime-rule summary for create/improve/debug in conversation |
With the app-development assistant / in-product browse
The create wizard and “improve the app in conversation” will:
- Inject App assistant brief every time (embedded under
backend/internal/appfromchat/appsdk_kb/) - Append at most two chapters of this directory’s originals by what the user said (data / handlers / UI / views / pack layout)
- On improve, also attach the current app pack files
After you open an app, the “App pack” panel can browse files in the pack; allowlisted paths can be edited and saved. Details: App package layout §4.1.
After you change docs in this directory, copy them into appsdk_kb/ and run go test ./internal/appfromchat/.
Sibling SDKs
| Directory | Aimed at |
|---|---|
sdk/appsdk (this directory) | Lightweight workspace apps |
sdk/host-embed | Legacy-host embed assistant |
sdk/platform-plugin | Plugin apps (apps-desktop iframe) |
sdk/agent-capability | Agent capabilities (call APIs from Messages) |
| Overview | sdk/README.md |
Source of truth vs implementation
| Topic | Location |
|---|---|
| Structure and validation | backend/internal/workspaceapp/spec.go |
| Standard UI renderer | client/web/src/WorkspaceAppRenderer.tsx |
| invoke / handlers sandbox | backend/internal/workspaceapp/invoke.go |
| Platform bridge | backend/internal/workspaceapp/platform_bridge.go |
| Employee-profile template | backend/internal/workspaceapp/employee_profile_*.go · skillfromchat/bundled/employee-profile/ |
| Runtime pack path | {RUNTIME_DIR}/workspaces/{workspaceId}/apps/{appSlug}/ |
What you can / cannot do
- Can: build tool pages with the three standard views; use
handlers+ the platform bridge to fetch data, write the DB, and generate previewable reports. - Cannot: reconstruct an arbitrary design-comp layout from a declarative description; for a complex operations console use pluginsdk. Choosing a path from a picture: App views.