Getting Started with the Experience Modernization Agent getting-started

The Experience Modernization Agent builds and changes Edge Delivery Services sites with you. You describe what you want in the Experience Modernization Console, and the agent imports pages, styles them, and writes the code. This guide takes you from access to a first page that you can edit, preview, and publish.

In Edge Delivery Services, a site’s code (blocks, styles, and scripts) lives in a Git repository, and its content lives in a separate content source that authors edit. The platform combines the two into fast pages. To learn more, see the platform overview.

In this guide, content is stored in the document-based content repository, where authors edit it in Experience Workspace, the visual authoring UI for Edge Delivery Services. If your content must stay in the JCR of an Adobe Experience Manager author instance, follow the guide for Experience Manager authoring for the steps that differ. To choose between the two, see Where Content Is Stored and How Authors Edit It.

Auto mode has its own sign-up. For console access and the terms that apply when you continue with your own site, see Access and AI Credit Usage.

Start with Your Own Pages first-outcome

Start with Auto mode below to migrate a few pages, review the result, and take it over with Make it yours. If you already have a project or want to guide the import from the beginning, start from a repository instead: create one from the boilerplate, or connect your existing site.

Both routes lead to your site connected in the console. From there, you prompt the agent, then save, preview, and publish the result. The console is hosted, so neither route needs a local development environment.

Before you import, choose a few pages of a site that you are authorized to migrate, including one of each common layout, and decide whether to keep the source design or apply a new one.

Start with Auto Mode brand-trial

Auto mode migrates a website, or a list of its pages, without step-by-step prompting. In the guided workflow, the agent stops after each step for your review. In Auto mode, it imports the content, migrates the design, critiques the result against the source, and keeps refining it until its critique finds the pages close to the source.

Because it checks and refines its own work, Auto mode takes much longer than a guided import of the same pages, so it suits a first result that you collect later. Once a run starts, it doesn’t ask for your input: you steer it only through the scope and options that you choose before you start. Auto mode starts from a website’s URL, not from a repository; if your site is already on Edge Delivery Services, connect it instead. It produces document-based content; for content stored in the JCR, use the guide for Experience Manager authoring.

Auto Mode Limits auto-mode-limits

Auto mode limits each account by the number of pages per migration, the number of migrations, and how many migrations can run at the same time. The Auto mode page shows the limits that apply to you before you start:

To stop a run, use Cancel migration. A cancelled run can’t be resumed; start a new migration instead.

Make It Yours make-it-yours

An Auto mode run creates its site in an Adobe-managed location. To keep working on it in your own site, select Make it yours on the finished run. This transfers the run’s code and content to a site that you own. It doesn’t migrate anything again.

Prepare the destination first:

To transfer the run:

The transfer copies the following:

The transfer doesn’t copy spreadsheets, such as redirects, bulk metadata, or placeholders; access permissions; site and organization configuration; or the run’s Git history and GitHub workflow files.

If the transfer stops with an error, nothing is merged into main, but code and content are transferred separately, so check both the branch and the pages. If the new branch already exists, choose another branch name.

A transferred site isn’t live yet. Agree who owns each remaining step:

In the console, continue with prompts to start with, then save, preview, and publish your changes.

Start from a Repository repo-start

To work in the console, a GitHub repository needs two GitHub apps with similar names and different jobs:

Create a New Site from the Boilerplate prepare-repo

Use this path for a new site, including one that you fill with pages imported from an existing website.

Bring Your Existing Site existing-site

If your site already runs on Edge Delivery Services, you don’t need to recreate it or migrate it again. Connect it, and the agent works on its code and content as they are.

Projects created from the current boilerplate include AGENTS.md, where you keep the project’s instructions for the agent, and a one-line CLAUDE.md that makes the agent load AGENTS.md in every conversation. Older projects may not have them; ask the agent to add them from the current boilerplate. See Project Instructions.

To restyle your site or build blocks, see Restyle an Existing Site and Block Development. A migration is not required.

Use Another Git Host other-git

Edge Delivery Services also supports GitHub Enterprise (self-hosted), Adobe-hosted repositories, GitLab, Bitbucket, and Azure DevOps. Onboard the repository in Adobe Cloud Manager, the Experience Manager as a Cloud Service tool for managing programs, environments, and code repositories. Then configure your site to use it. See Bring Your Own Git.

Open the Experience Modernization Console open-console

The console keeps a hosted working copy of your project, called the console workspace in these docs; it is unrelated to Experience Workspace, the authoring UI. The agent imports content and changes code there until you upload or push. The console sets up your workspace the first time you sign in, which can take up to 10 minutes. Each Adobe organization that you sign in with has its own workspace, with its own projects and chats; to switch, sign out and sign in with the other organization’s profile. After a period of inactivity, the workspace pauses. When you return, the console shows Your workspace is paused; select Wake up and wait a few minutes while it is restored.

Demo Mode demo-mode

If the console opens in demo mode, a Demo site button shows in the header. You can explore the sample project and try importing pages, but work in the demo site isn’t saved, and the demo site can’t push code to GitHub or upload content to Experience Workspace.

Connect Your Site connect-repo

Connect the site that you created from the boilerplate, transferred with Make it yours, or already had.

Your site and its GitHub repository are now connected to the console.

Confirm the connected repository, branch, and content destination before requesting changes. Connecting needs write access to the repository. If your organization or repository isn’t listed, or the console can’t verify the preview URL, see Git Connection Problems.

Console Home console-home

Until you start a conversation, the console opens on its Home page. Type a request, or select one of the suggested prompts, which are grouped by task. A request that you type runs at once. Most suggested prompts run in Plan mode: the agent proposes its steps without changing any files, and you select Execute plan to carry them out.

Start Prompting start-prompting

Once your site is connected, describe what you want in plain language. Say what result you expect and on which page, rather than how to write the code. The agent knows Edge Delivery Services, so you can also ask it how a part of your site works or what a platform term means. To learn how a page is built from sections, blocks, and default content, see Markup, Sections, Blocks, and Auto Blocking.

On a new site, start by importing a page step by step. On a site that already has pages, such as your existing site or one transferred with Make it yours, ask the agent to explain the project, then make a visual change with Inspect mode or import further pages. See Prompts to Start With.

Import a Page Step by Step guided-import

Importing pages from an existing website is the most common way to start. In the guided workflow, the agent stops after each step so that you can check it: first the page’s content, then its design. Save each result as soon as you have checked it: upload the content after the content step, and push the code after the design step.

The page import doesn’t build the shared navigation and footer; ask for them separately. Next, preview and publish the page. For more pages, repeat these steps and ask the agent to reuse the blocks that it has created. Once your first pages look right, ask it to document its blocks and styles for later conversations; see Let the Agent Maintain the Files.

Make a Visual Change with Inspect Mode inspect-mode

On a site that already has pages, such as your existing site or a site that you transferred with Make it yours, a visual change is the quickest way to see a result. Point at what you want to change rather than describe where it is: turn on Inspect mode in the preview panel, select the element, and describe the change, for example “Make this button use the primary button style”. Make Your First Change gives the steps, including how to check each screen width and undo a change. Then push the code to keep it.

Prompts to Start With first-prompts

Replace the example URLs and paths with your own.

A new site from the boilerplate:

After Make it yours:

Your existing site:

Prompting Tips prompting-tips

The agent knows only what is in the current conversation and in your project’s files. Give it the context that it can’t know, such as requirements, brand rules, screenshots, and links to the documentation of other systems; see Give the Agent Context. To make it follow your project’s conventions in every conversation, ask it to write them in AGENTS.md and the files that AGENTS.md lists; see Project Instructions and Memory. For prompts for each task, see the Prompting Guide.

Save, Preview, and Publish save-work

The agent’s work stays in the console workspace until you save it elsewhere. Each of the next steps moves work to a different place:

Upload and push separately. Edge Delivery Services stores content apart from code, so pushing code doesn’t save your pages, and uploading doesn’t save your code. Your first result is complete when you can reopen the page in Experience Workspace, edit it, and see the requested change on the preview site, not merely when a preview link exists.

Upload Content upload-content

Upload the pages to the document-based content repository, where authors edit them in Experience Workspace. Some console labels and screens still say Document Authoring. Before you upload, confirm the destination and that you may replace any existing pages there. The upload uses your own content permissions; see Content Push Permissions. For Experience Manager authoring, follow Upload Content in the guide for that setup instead.

To find the uploaded content, select View in AEM in the notification when the upload completes, which opens the site’s content in Experience Workspace, or go to https://da.live/#/{organization}/{repository}.

Open an uploaded page, make an edit, save, and reopen it to check that authors can edit it and that the change persists. Where Experience Workspace is turned on for the site, Edit in Experience Workspace in the console opens the selected page in its visual editor.

Push Code Changes push-code-changes

Review the code diff and run the project’s checks before pushing. Use a pull request for work that needs review; for what enforces review, see Control over Changes.

If a pull request was created, select View PR in the completion notification. Otherwise, such as for a repository connected through Cloud Manager, verify the commit on the destination branch. If the branch is protected against direct pushes, push with Create new PR.

Your code is now in GitHub. It shows on that branch’s preview and live URLs straight away.

Commit Identity commit-identity

The console commits with the Git identity, user.name and user.email, configured in your console workspace, and uses a default value for either one that is missing. Neither connecting your Git account nor the Git settings on your own computer set this identity.

If Someone Else Changed the Branch push-conflicts

A branch is a sequence of saved changes, called commits. Your console workspace holds the branch as it was when you last pulled it, so if someone else has pushed to it since, the repository has commits that your workspace doesn’t. Push to current branch then adds your commit after theirs and pushes again. If you changed different files or lines, this succeeds without anything more from you.

If you both changed the same lines, Git can’t decide which version to keep. This is a conflict. The console shows Push failed: Remote has conflicting changes that cannot be merged automatically, keeps your changes, and switches the dialog to Create new PR.

The console doesn’t merge branches or resolve conflicts itself. Sync > Pull > Code works the same way: if your commits conflict with the remote changes, it cancels the pull, leaves your work as it was, and suggests pushing to a new branch or asking the agent to help. To avoid conflicts, pull before you start a task, push small changes often, and agree with your team who changes which files. See Work as a Team.

Preview Site preview-site

The console’s preview panel shows only the working copy in the console workspace. To check the uploaded pages on the preview site with your code:

Verify that the preview contains both the saved content and the intended code version.

If your code is on a branch other than the one in the preview URL, change the preview URL to that branch. For Experience Manager authoring, follow Validate Authoring and Preview instead.

Publish publish

When the preview looks right, publish the page to make it live on *.aem.live:

Publishing makes the page public. Who can publish is set by the site’s publish role; follow your team’s review process. Code doesn’t need this step: it goes live as soon as it reaches main. See Control over Changes.

Create a Customer Demo customer-demo

A demo shows a few complete, branded pages of a site that you are authorized to use, along a path that you walk your audience through. It needs no production cutover, and shouldn’t be presented as production-ready.

Access and AI Credit Usage access

Request access to the Experience Modernization Console through your Adobe account manager, and sign in with an Adobe ID that belongs to your company’s Adobe organization. Auto mode needs no request through your account manager; sign up on its page, as in Start with Auto Mode.

Plan your migration as part of your move to Edge Delivery Services. Your Adobe account team can review the scope and commercial arrangements for your project, including large-site and partner-led migrations. Your organization’s agreement determines the applicable AI credit allowance and migration terms; signing in alone doesn’t establish your entitlement.

Under the current credit model, migrating pages can consume AI credits:

For an introduction to AI credits across Adobe’s agentic capabilities, see AI credit consumption. Examples or rates for other capabilities don’t establish the terms for your migration. Ask your Adobe account team to review your organization’s usage and confirm which usage reports are available to you.

Troubleshooting troubleshooting

For problems with imports, source access, uploads, previews, Git connections, or the console workspace, see Troubleshoot the Experience Modernization Agent. If that doesn’t solve the problem, request support from the team that builds the agent.

Additional Resources additional-resources