Agents and Summer Apps

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

Everything a person sees in a Summer App, an agent can read and use. To build one, see Build an app 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):

{ "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 (collections). That is how an agent asked to “add a note” knows what a note looks like. Write (one revision, applied in order):

{
  "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 (agentTools) and handles them in its code:

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:

{ "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:

{ "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). 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.
`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.

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.

Start here

Create and publish your game

Other ways to start

Essentials

Models

Using Summer

Summer Studio

Summer Apps

Other Engine Migration

Automation

Reference

Data is the API

Agent tools

Events: the app talks back

The page an agent can use

The MCP tools

Skills

​Data is the API

​Agent tools

​Events: the app talks back

​The page an agent can use

​The MCP tools

​Skills

Data is the API

Agent tools

Events: the app talks back

The page an agent can use

The MCP tools

Skills