# Hand a module to your agent

URL: https://kywi-docs-production.up.railway.app/agent/hand-a-module-to-your-agent
Type: docPage

Copy reference gives a module or section a one-line kywi: address; paste it with your request and the agent finds it with resolve_ref instead of guessing.

Describing a module to an agent ("the heading in the second band on /about") makes it read the whole layout and guess. Instead, copy the module's reference in the editor and paste it into your request. The agent passes the line to `resolve_ref` on the site MCP server, gets back exactly where that node is and what it holds, and either edits it or tells you why it shouldn't.

## Copy the reference

Every module and section in the layout editor has a **Copy reference** action: the link icon in a module's action bar, and a labeled button in a section's toolbar. It is there in both the admin Layout tab and Design on site, including modules and sections inside a personalization or A/B arm. It isn't offered while you edit a reusable component's definition or a blueprint, or on a page that hasn't been created yet, because none of those is a page an agent can address.

Copying changes nothing on the page: no unsaved changes, no entry in undo history, nothing selected or deselected. You'll see **Reference copied**. If the browser won't give the editor the clipboard, the line appears in a field, already selected, for you to copy by hand.

## What the line says

kywi:marketing/page/3f2a91c0-5b7d-4e2a-9c1f-8d6e0b4a2c17/m/7c91e2d4-0a3b-4f6e-8d2c-1b5a9e7f3c60 — Heading "Run the whole room" on /about

Everything before the dash is the address: the site, the content type, the page's id, `m` for a module or `s` for a section, and the node's id. The site is the site's slug when the editor knows it, otherwise its id or `_`; the page id alone is enough to find the page. After the dash is what you were looking at — the module's name, the start of its text and the page's path, or for a section its first text and how many modules it holds. The agent uses that to check it found the thing you meant.

## The default page, or a variant

A page variant or a page-level A/B variant starts as a copy of the default page and keeps its node ids, so the same id can be in several versions of one page. A reference copied while one of those is on screen ends with `@pv:…` or `@ab:…:…` to say which. A reference without that ending always means the default page. If the node has since gone from the default page but still exists in a variant, the agent gets the locations and no edit arguments, and should ask you which one you meant. Copying the reference again from what's on screen settles it.

## Paste it with the request

kywi:marketing/page/3f2a91c0-5b7d-4e2a-9c1f-8d6e0b4a2c17/m/7c91e2d4-0a3b-4f6e-8d2c-1b5a9e7f3c60 — Heading "Run the whole room" on /about Make this heading shorter, under six words, same meaning.

## Using the site MCP server. Replace the first line with the line you copied.

The agent calls resolve_ref with the line, checks the module is the heading you described, then calls update_module_props with the arguments resolve_ref returned. If the module is in an arm or a variant, it confirms with you and edits through get_layout and update_layout; for a linked component, an ambiguous reference or one it can't match, it asks you before changing anything.

You don't have to name the tool: `resolve_ref`'s own description tells the agent to call it first whenever it sees a `kywi:` reference, and the building-patterns guide (in an AGENTS.md generated at 0.31.0 or later) says the same. `resolve_ref` is on the site server only; see [Two servers, two jobs](/agent/two-servers-two-jobs/).

Save or discard your own changes in the editor before the agent writes, and reload the editor once it has to see its change. If you save over it, you're asked to reload or overwrite, and overwriting drops the agent's edit.

## What the agent gets back

The page (id, title, path, status); where the node sits (region, section, column, and any personalization or A/B arm or page variant); its current props and style; and, for a built-in module, its props schema. A custom module's schema lives in `kywi.config.ts`, which the site server can't read, so the agent works from the props on the node. When the node can be edited directly, the result carries ready-made arguments: `update_module_props` and `remove_module` for a module, `add_module` and `remove_row` for a section.

It also carries a design hint. Text and settings are props. Spacing, background and colors are the node's style, set with [theme tokens and style overrides](/authoring/module-properties-theme-tokens-style-overrides/). A custom module's markup is its React component in your code, so a request like "make this card's image round" is a code change there. A built-in module's markup isn't yours to change; the agent can use props and style, or propose a [custom module](/developing/build-a-custom-module-the-three-part-contract/).

## When the agent shouldn't edit it directly

**Inside a personalization or A/B arm, or a page variant.** The module tools only reach sections placed directly on the default page. For anything else the agent reads the whole layout with `get_layout`, changes that node, and writes it back with `update_layout`. The change reaches only the visitors who get that arm or variant, so a good agent confirms that's what you meant.

**A linked component.** If the module, the section around it, or the container it sits in is a [linked component](/authoring/living-with-linked-components/), the result has no edit arguments. The live page renders the component itself, and changing the component changes every page that uses it, so the agent should check where it's used and ask you first. Editing just this placement would quietly turn it into a one-page copy that stops following the component; if that's what you want, detach it in the editor first.

**The same id in more than one place.** The result lists every place and gives no edit arguments until you say which one.

**A stale reference.** If the node, or the variant the reference names, was removed after you copied it, the agent gets the page's current sections and modules plus your description, and should match them and check with you before changing anything. A reference from a different Kywi site isn't resolved by this site's server; it tells the agent to use the server for the site it came from.

## Developers: which site the reference names

A page rendered with `createPublicPage` names its site by slug. A hand-written route that mounts the front-of-site editor itself should pass `siteSlug`; see [The host-app contract](/developing/the-host-app-contract/).
