What Agents Can Do
Gavana is a visual canvas for people and a precise, revision-safe contract for agents. The same canvas your team edits in the browser is the canvas an agent reads, extends, and generates into — with stable handles, atomic writes, and an audit trail on every change.
This section is for connecting an agent and running real work through it. If you want the raw HTTP contract, go to the API. If you want tool-by-tool MCP detail, go to MCP.
Connect your agent
Not sure which? The connection overview compares the three transports side by side.
| You want to… | Use | Authentication |
|---|---|---|
| Let a chat client work with canvases | Hosted MCP | Browser OAuth |
| Give a local coding agent the full tool surface | Local MCP | Personal Access Token |
| Script or automate from a terminal | The CLI | Browser OAuth or a token |
| Build your own service or backend | The Canvas API | Personal Access Token |
| Only inspect, never change anything | Hosted MCP using only read-only tools, or gavana auth login --read-only | Browser OAuth |
What an agent can actually do
| Capability | What it means | Costs credits? | Scope needed |
|---|---|---|---|
| Inspect | List canvases, read a canvas graph, read a node, list assets, render an SVG preview | No | canvas:read, asset:read |
| Validate | Audit the current graph, or a proposed batch, for structural problems | No | canvas:read |
| Edit | Create, update, move, resize, delete nodes; create and delete connections; apply an atomic batch | No | canvas:write |
| Reuse Elements | List exact immutable visual references; create revisions; organize, archive, and restore them | No | element:read; management also needs element:write |
| Discover workflows | Search Recipes, list and inspect Image Actions | No | canvas:read |
| Discover models | List saved AI connections and models | No | image:generate or video:generate |
| Deterministic Actions | Resize, crop, change aspect ratio, composite, add text, overlay, colour grade, rotate | No AI credits | canvas:read, canvas:write, asset:read (a local file input also needs a generation scope for the private upload) |
| Recipes | Fork a Recipe card (setup only), or run one (execution) | Run costs credits | image:generate and its dependencies |
| Image generation | Generate, edit, or produce variations into a canvas; optionally apply up to eight version-pinned Elements | Yes | image:generate and its dependencies; add element:read when Elements are applied |
| Video generation | Discover video models and generate video from a prompt or frames | Yes | video:generate and its dependencies |
| Observe | Wait for, poll, and cancel a Run or Job | No | job:manage |
The two lines that matter most: editing a canvas costs nothing, and generation costs money on the user’s own connected provider account. Everything in the safety contract flows from that split.
The persistent Agent Canvas
Every account has one persistent Agent Canvas. It is the default destination when an agent needs somewhere to put work and no specific canvas was chosen. Resolve it with gavana canvas agent, or by passing --destination agent-canvas to any image, Action, or Recipe command.
Use it for scratch work and handoffs. Use a named canvas — --destination canvas:OWNER_UID:CANVAS_ID — when the output belongs to a real project.
Where an agent’s work shows up
Every change carries provenance. The label you give a token when you create it (“Claude Code · MacBook Air”, “Codex · CI”) is written into node and activity records, so a reviewer can tell which client made which change without trusting a caller-supplied name. That is the reason to create one token per client and per machine rather than sharing one.
Read operations return structured canvas data and stable handles. Generation returns a run: or job: handle for observation, and — once complete — durable node: and asset: handles. The temporary observation handles expire; the durable handles are what you keep.
Before you connect an agent
Generation runs on the AI provider connection the account owner configured. Approving an image, Recipe, or video run means approving a real charge on that provider. Give an agent image:generate or video:generate only when you intend it to spend.
New hosted connections use /mcp, and new Personal Access Tokens use all eight scopes with Never expiry. Use a narrower token or a custom expiry only when you deliberately need that boundary.
Generation remains separate from connection setup: the agent must have explicit current-turn approval before it starts a paid image, Recipe, or video run.
The contract
Every Gavana agent operates under the same eight-rule contract: read before you write, get explicit current-turn approval before paid work, never auto-retry a paid request, keep credentials out of chat and logs, share only the request ID with support, use only handles the service returned, reuse a caller-stable idempotency key, and read baseRevision before a raw canvas write.
Gavana serves that contract to agents at runtime through the guide_search and guide_get tools and the gavana://guides/canvas/v1/ MCP resources, so a connected agent can look it up mid-task.
Start here
Machine-readable references
This help center publishes an LLM index and complete help-center context alongside its normal pages. For exact API operations and schemas, use Gavana’s generated OpenAPI 3.1 document rather than inferring an endpoint or a parameter.