> ## 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.

# Agents and Summer Apps

> Summer Apps are built for agents: an app's shared data is its API, apps give agents new tools, and agents build, see and change every app through the summer_app MCP tools.

<Warning>
  **Draft.** Summer Apps is in a closed test. This page goes live after the end-to-end test on production.
</Warning>

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

## Data is the API

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

Read (no `ops`):

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

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

Write (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": "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](/apps/manifest) (`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 becomes `tool_failed`.

Your agent lists the tools with `summer_app_tools` (`{ appId, version, tools, collections }`) and runs one with `summer_app_call`:

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

The answer is `{ ok: true, 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 `app_not_open`: use `summer_app_data`, or ask the person to open the app.

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 `summer_app_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](/apps/sdk)). While the app is open, `summer_app_page` reads them (no `fill`, no `press`), 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 `app_not_open`.

## The MCP tools

The hosted Summer Engine MCP (`https://mcp.summerengine.com/mcp`) and the `summer-engine` npm package have the same `summer_app_*` tools, except `summer_app_dock`, which is only in the npm package and comes with the next Summer Engine update.

| Tool | Does |
| - | - |
| `summer_app_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 KB). Read `overview` first, then what the app needs. |
| `summer_app_list` | The apps in the person's workspaces. `workspaceId` and `q` (search) are optional. |
| `summer_app_create` | A new scratch app: `{ name, purpose, format, workspaceId?, folder? }`. `format` is `code` (default) or `layout`. Returns `{ app, studio, url }`; the app id is `app.id`. The person's Studio tab opens it. `studio.reason: "no_tab"`: no tab was open; give the person `/studio/apps/<appId>`. |
| `summer_app_publish` | A new version: `{ appId, files or layout, manifest, note?, idempotencyKey? }`. Files are `[{ path, content, encoding }]` (`utf8` or `base64`). The npm package also takes `dir`, a local folder. The answer can carry `warnings`: SDK calls whose permission the manifest lacks, and undeclared `agentEvents` or `agentTools`. Fix them and publish again. |
| `summer_app_update` | Renames an app or changes its purpose, folder or status: `{ appId, name?, purpose?, status?, folder? }`. `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. |
| `summer_app_get` | `{ app, version, files, data, url }`: the manifest, the current files and a summary of the data. Read it before you change an app. |
| `summer_app_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. The npm package also takes `out`, a local path for the PNG. See [Build with your agent](/apps/build-with-your-agent). |
| `summer_app_events` | Waits for what the app sends, errors, feedback and tool calls. |
| `summer_app_page` | Reads or uses the fields and buttons an open app declared. |
| `summer_app_data` | Reads or writes the app's shared data. |
| `summer_app_tools` | The app's agent tools and data collections. |
| `summer_app_call` | Runs an agent tool in the open app. |
| `summer_app_report_gap` | Tells Summer about a capability an app needed and the SDK lacks: `{ capability, detail?, method?, appId? }`. |
| `summer_app_dock` | npm package only. Docks an app in the running Summer Engine editor. Coming with the next Summer Engine update; see [Engine and docks](/apps/engine-and-docks). |

All of them except `summer_app_call` (which can run a tool that generates) are free.

## 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.