Skip to main content
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 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:
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 (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):
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 (agentTools) and handles them in its code:
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:
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:
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.

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