> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Summer Apps for agents: data, tools, events and operations

> How agents use Summer Apps through the Summer MCP: read and write an app's shared data, run its agent tools, wait for its events, and the full apps.* operation list.

Everything a person sees in a Summer App, an agent can read and use. To build one, see [Build an app with your agent](https://docs.summerengine.com/apps/build-with-your-agent.md).

## Data is the API

An app keeps its shared data in **collections** of JSON records. Your agent reads them with `apps.read_data` and writes them with `apps.write_data`, with no app open. Every write is one revision, and everyone with the app open sees it live.

`apps.read_data`:

```json theme={null}
{ "appId": "<app id>", "collection": "items" }
```

The answer is `{ revision, items, nextCursor, collections, declaredCollections }`; `items` are the records. Leave out `collection` to read every collection. `limit` is 1 to 500 (default 50); pass `nextCursor` as `cursor` for the next page. Removed records are not returned. `declaredCollections` is the record shape the app declares in its [manifest](https://docs.summerengine.com/apps/manifest.md) (`collections`). That is how an agent asked to "add a note" knows what a note looks like.

`apps.write_data` (one revision, applied in order):

```json theme={null}
{
  "appId": "<app id>",
  "ops": [
    { "op": "patch", "collection": "items", "recordId": "bow", "patch": { "damage": 36 }, "ifRevision": 7 },
    { "op": "put", "collection": "items", "recordId": "axe", "data": { "name": "Axe", "damage": 50, "speed": 0.8 } },
    { "op": "remove", "collection": "items", "recordId": "old-sword" }
  ]
}
```

The answer is `{ revision, operation, records, replayed }`.

* 1 to 100 ops per call. A record is JSON up to 64 KB. Record ids: letters, digits and `_ . : -`, max 128 characters.
* `put` creates or replaces. `patch` merges keys (`null` removes a key). `remove` deletes.
* A record's `revision` is the app's data revision at the record's last write: one counter for the whole app, not one per record. `ifRevision` applies an op only if the record is still at that revision. Take it from the record's `revision` in your last read. `0` means "only if it does not exist yet". A mismatch fails the call with `conflict`: read again and retry.
* Your writes are recorded with `actor.kind: "agent"` and your agent's name, and as `createdBy` on records you create. The app can show which rows an agent made.
* `"as"` is `agent` (default) or `seed`. `"as": "seed"` writes starter data that belongs to the team: `kind: "seed"`, shown with no author. Use it to fill a new app.

## Agent tools

An app can give agents its own logic, for example a balance formula. It declares the tools in its [manifest](https://docs.summerengine.com/apps/manifest.md) (`agentTools`) and handles them in its code:

```js theme={null}
summer.agent.tool("nerf_item", async ({ id, percent }, { agent }) => {
  const items = summer.data.collection("items");
  const record = await items.get(id);
  if (!record) throw new Error(`No item ${id}`);
  const damage = Math.round(record.data.damage * (1 - percent / 100));
  await items.patch(id, { damage }, { ifRevision: record.revision });
  return { id, damage };
});
```

`agent` is the name of the agent that called. Data writes made while the handler runs are recorded with `actor.kind: "agent"` and `via: "agent-tool"`. Return JSON under 100 KB; a throw fails the agent's call with the error `unavailable` and the tool's message.

Your agent lists the tools with `apps.tools` (`{ appId, version, tools, collections }`) and runs one with `apps.call`:

```json theme={null}
{ "appId": "<app id>", "tool": "nerf_item", "input": { "id": "bow", "percent": 10 } }
```

The answer is `{ result, seq }`. The call runs inside the app open in the person's Studio tab, with their rights, and waits up to 60 seconds. If the app is not open, the answer is the error `conflict`, and its `next` step is the app's link for the person to open. For plain data, use `apps.read_data` instead.

Use data for plain reads and edits. Use a tool for logic that lives in the app.

## Events: the app talks back

An app sends events to your agent with `summer.agent.send(name, payload)`, for example when the person presses "Send to agent". Your agent waits for them with `apps.events`:

```json theme={null}
{ "appId": "<app id>", "after": 0, "timeoutSeconds": 50 }
```

The answer is `{ events, cursor, timedOut }`. Each event is `{ seq, kind, actorId, payload, createdAt }`. Pass `cursor` as `after` in the next call. `timeoutSeconds` (0 to 50, default 25) is how long the call waits for the first new event.

| `kind` | Payload |
| - | - |
| `agent` | `{ name, payload }` from `summer.agent.send` |
| `error` | `{ message, source?, line?, column?, stack? }`: an uncaught error in the app, or a `console.error` line |
| `feedback` | `{ thumbs?, note? }` from the person |
| `tool` | An agent tool call and its result. Not returned by default; ask with `"kinds": ["tool"]`. |

## The page an agent can use

An app declares its inputs and buttons with `summer.page.declare` (see the [SDK reference](https://docs.summerengine.com/apps/sdk.md)). While the app is open, `apps.page` reads them, and `apps.use_page` fills fields (`"fill": [{ "field": "<id>", "value": 12 }]`) and presses a button (`"press": "<action id>"`). Buttons marked `critical` (delete, publish, pay, send) are pressed only by the person. If the app is not open, the answer is the error `conflict`.

## The operations

On the Summer Engine MCP (hosted at `https://mcp.summerengine.com/mcp`, or the `summer-engine` npm package), your agent runs them with `summer_call`: `{"op": "apps.create", "input": {...}}`. `summer_search "summer app"` lists them with their inputs. The `summer-engine` npm package also has two local ones: `apps.publish_folder` (publish a local folder; its npm MCP tool is `summer_app_publish`) and `apps.dock` (`summer_app_dock`). Every input and answer: [Summer Apps operations](https://docs.summerengine.com/mcp/operations/apps.md).

| Operation | Does |
| - | - |
| `apps.guide` | The build guide, as Markdown. `section`: `overview` (default), `examples`, `sdk`, `manifest`, `kit`, `design`, `layout`, `types` (the SDK's TypeScript types) or `all` (every section except `types`, about 100,000 characters). The answer stops at `maxCharacters` (default 24,000, up to 200,000) and says `truncated`. Read `overview` first, then what the app needs. |
| `apps.list` | The apps in the person's workspaces. `workspaceId` and `q` (search) are optional. |
| `apps.create` | A new scratch app: `{ name, purpose, format, workspaceId?, folder? }`. `format` is `code` (default) or `layout`. Returns `{ appId, app, workspace, studio, url }`; `workspace` says which team it went to and why. The person's Studio tab opens it. `studio.reason: "no_tab"`: no tab was open; give the person `/studio/apps/<appId>`. |
| `apps.publish` | A new version: `{ appId, files or layout, manifest, note?, idempotencyKey? }`. Files are `[{ path, content, encoding }]` (`utf8` or `base64`). The answer can carry `checks`: SDK calls whose permission the manifest lacks, and undeclared `agentEvents` or `agentTools`. The publish went through; fix them and publish again. With the npm package, `apps.publish_folder` publishes a local folder. |
| `apps.update` | Renames an app, changes its purpose, folder or status, or pins it: `{ appId, name?, purpose?, status?, folder?, pinned? }`. `pinned` puts it in the person's own Studio sidebar; any member may pin. `status` is `scratch`, `kept` (the team keeps it) or `archived`. Archive the throwaway apps you made when the person is done with them. `folder: null` takes an app out of its folder. |
| `apps.get` | `{ app, version, files, data, url }`: the manifest, the current files and a summary of the data. Read it before you change an app. |
| `apps.screenshot` | Renders the published app headless and read-only, with the person's data. Returns the picture plus console lines, errors, refused calls, `connected` and `rendered`, and the declared fields, buttons and agent tools. `{ appId, width?, height?, theme?, fullPage?, version?, params?, steps? }`. `steps` (up to 5) click a selector, press a declared action or wait before the capture. See [Build with your agent](https://docs.summerengine.com/apps/build-with-your-agent.md). |
| `apps.events` | Waits for what the app sends, errors, feedback and tool calls. |
| `apps.page`, `apps.use_page` | Read, or fill and press, the fields and buttons an open app declared. |
| `apps.read_data`, `apps.write_data` | Read or write the app's shared data. |
| `apps.tools` | The app's agent tools and data collections. |
| `apps.call` | Runs an agent tool in the open app. |
| `apps.feedback` | Sends the person's thumbs up or down and a note to the app's makers: `{ appId, thumbs?, note? }`. The app's agent reads it in `apps.events`. |
| `apps.report_gap` | Tells Summer about a capability an app needed and the SDK lacks: `{ capability, detail?, method?, appId? }`. |
| `apps.add_starter`, `apps.duplicate` | Add one of Summer's starter apps (`pick-one`, `asset-tracker`, `balance-table`, `live-ops`) to a team, or copy an app and its live version (not its data) into a new scratch app. |
| `apps.update_starter` | Makes the newest starter the live version of a starter app the team changed. Asks the owner first. |
| `apps.delete`, `apps.rollback` | Delete an app (asks the person first), or make an older version the live one (asks the app's owner). |
| `apps.publish_folder` | npm package only. Publishes a local folder (`dir`) as a new version, like `apps.publish`. |
| `apps.dock` | npm package only. Docks an app in the running Summer Engine editor, closes it or lists docks. Coming with the next Summer Engine update; see [Engine and docks](https://docs.summerengine.com/apps/engine-and-docks.md). |

The 3.x tool names (`summer_app_create`, `summer_app_data` and the rest) keep working for all of 4.x: `summer_call` accepts them. Each one's 4.x operation: [3.x tool names](https://docs.summerengine.com/mcp/operations/legacy-names.md). All of these operations are free except `apps.call`, which can run a tool that generates.

## Skills

The Summer skill library has two skills for apps: `summer-apps` (when to build an app, layout or code, the build loop, data, tools and events) and `summer-apps-design` (how an app must look). The npm package installs them with the rest of the library.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.