Personal agents

A personal agent is an open-source shopping agent that runs on its own machine in our cloud and shops at a store over UCP. Use one to test how an agent shops with the buyer profile, instructions and skills you give it, and see what it did and what changed in its files. Every call is recorded as a normal run.

What a personal agent is

The agent: Goose (the default) or Hermes, each on its own machine in our cloud. The machine sleeps when the agent is idle and starts when a message arrives.
Its skills: Anthropic's five shopping skills, customer-care, memory-personalization, planning-goals, purchase-research and search-discovery, beside any skills the agent ships with.
What it can reach: only the model and the store, both through Playground. It reaches the store through its UCP APIs, never its website. Terminal, file tools, web and browser are off.
The record: each model call and store call goes through Playground, so the run is recorded like any other run. Store calls carry Playground's signed UCP agent profile, as on every run.

Where to find it

Personal agents are for signed-in personal accounts. A team workspace doesn't have them; switch to your own account to use them. Signed out, Runs shows the fresh agents greyed with Sign in to use.

On Runs: open the Where it runs pill under the message box. It has two groups: Your personal agent (your saved agents, and Set up a personal agent…) and Fresh each run (Goose (fresh) and Hermes (fresh)).
In Settings › Personal agents: Your agents (with New agent… and Manage… for each), Saved file sets, and What each agent starts with, where View opens each agent's files as it ships.

Fresh each run, or a saved agent

Fresh each run: a new install every run. Pick it and press Send; there is nothing to set up. Its memory and files are cleared after the run; the run itself is kept.
A saved agent keeps what it learns from one run to the next: its memory and files carry over. You can have up to 3 at a time. Set one up from Runs (Set up a personal agent…, then Set up agent in place of Send) or from Settings (New agent…). Give it a name and pick Goose or Hermes.

Before the first run, the Info pane shows what the agent will start with, what is Off, and Your files: "Kept until you delete the agent; never in a shared run."

Starting files

Start from picks the files the agent begins with. For a saved agent this is its first run; for a fresh agent, it is for that run only.

Its defaults: the agent's files as it ships.
A saved set: one of your saved file sets (see below).
Example buyer: the defaults with an example buyer profile in its memory.

The Starts with row says what that comes to, for example "SOUL.md changed · 4 of 5 shopping skills · 58 of its own · memory empty", and ends with Review and change….

Review and change…

The dialog lists the agent's files on the left, grouped Instructions, Memory, Shopping skills, Its own skills and Yours, and shows the open file on the right. There is one file per slot:

Instructions: Hermes reads SOUL.md, how the agent talks and decides. Goose reads .goosehints, instructions it reads every run.
Memory: what the agent knows about its buyer. Hermes keeps it as memories/USER.md, Goose as memory/user.txt. It starts empty.

For the open file:

Edit changes it in place.
Replace with your file… puts one of your files in that slot.
Reset to default (or Reset to empty for memory) puts it back.
Use an example profile fills the memory slot.

Each shopping skill has its own switch, and the agent's own skills share one. The agent won't have a skill that is switched off, so it can't read it. Add a skill… adds a skill of your own, named from its front matter. Each changed file is marked changed, and the Changes from default tab shows every difference from the defaults as a diff. Use these keeps your choices for the agent.

Example profiles

Four kinds of buyer for each store type, Retail, Food and Stays, all written by us; none is a real person. The menu offers the set for the store you're testing (in Settings, with no store yet, all three, grouped by type). Each fills the memory slot, and the run records which one it started with, for example "Loyal customer (Food)".

Loyal customer (what Example buyer uses)
First-time buyer
Strict budget
Whatever you suggest

What a file may hold

Every file you add, replace or upload is checked before it reaches the agent:

Names the agent reads: SOUL.md, .goosehints (Goose only), memories/USER.md, memories/MEMORY.md or skills/<name>/SKILL.md. A file with any other name isn't added.
Text only: a file that isn't text isn't added.
Sizes: up to 256 KB a file, and at most 20 files and 1 MB in all. Over the totals, nothing is added.
Keys and tokens are refused: a file that looks like it holds an API key, token, password or private key isn't added, and the check names the line. Take the key out first.
Personal data is flagged: a file with an email address or phone number is added, with a note that the agent will read them. Anything the agent sends to a store is recorded in the run.

Download and upload again

Download in the files dialog (Download these files in Settings › Personal agents › Manage…) gives a .zip of the files as the agent keeps them, with a manifest.json naming the agent, its release, the version of the files, where they came from, and each file's path and hash. The agent's own skills are left out unless you tick them.

Edit the files on your machine, then use Upload a .zip… in Review and change…. Each file goes to its slot, and the dialog opens on Changes against the version the download came from. If that version isn't one we kept, it compares with the files before the upload and says so.

A .zip may be up to 4 MB, with at most 600 entries and 8 MB unpacked. A path outside the agent's files or a link refuses the whole .zip, and a Goose download won't go into a Hermes agent (or the other way round). Each file inside gets the same checks as above.

Saved file sets

A saved set is starting files you can pick when you set up an agent: SOUL.md, memories and your own skills. Make one with New file set… in Settings › Personal agents, or with Save as a file set… under More in any files dialog, including the files of a finished run. A set keeps your files only, never the shopping skills, and its files get the same checks as an upload.

Editing a saved set makes a new version. Agents that started from the old one keep it, and their runs still show which version they used: Info's Starting set row names the set and its version.

Reading a run

A personal-agent run has the same page as any run: chat, Trace, Timeline and Info. A few things are its own.

The START line, one per message, says how the agent began: "Your agent started · it was asleep · files restored", "Your agent was awake · files ready", or for a fresh agent "Your agent started · new install" (with "· your files" when it started from files). Opened, it shows how long the machine took to start and the files to restore. If the agent didn't start, the line says why.
Agent files lines, one per message, say what changed in the agent's files, such as "Agent files: changed memories/USER.md · 2 lines", or "Agent files: no change". Opened, a line shows the diff, and View files opens the files dialog for that message.
The agent's own calls on its memory and skills have their own Trace lines, apart from store calls.

The files dialog has these tabs:

Changes: the changed files as a diff, for the whole run or one message, unified or before and after.
At start: every file as the run began, with its text.
After this run: every file as the run ended.

In Info:

Started with: what the agent started from, such as "Goose defaults + 1 change · user.txt from the example Loyal customer". It opens the files against the defaults.
Memory calls: how many times the agent read and wrote its memory, or "None asked for in this run".
Also Where it ran, Agent, Store calls, Files changed (opens After this run), Skills read and Profile it sent.

On the Timeline, a run where the agent used its memory or skills gets a Memory and a Skills track. They sit outside the shopping funnel and don't count as progress towards an order.

Who sees what

Agent files are the account owner's only. You see their names, text and diffs, and can download them.
Shared runs and teammates see how many files changed, never the files' names or contents, and no files dialog or download.
The system prompt is never shown, on any run.

Your files

Kept until you delete the agent; never in a shared run.

Deleting an agent (Settings › Personal agents › Manage… › Delete…) removes its files and every version of them, and removes its machine. Its runs keep their calls, answers and the names and counts of what changed. This can't be undone.

Test stores only, for now

Personal agents shop at our test stores: any *.ucpsandbox.com store, such as flowers.ucpsandbox.com. On another store, Runs shows them greyed with "Personal agents shop at our test stores for now".

Order webhooks

Order webhooks work the same as on any run: they go to Playground, not to the agent, and show in the Trace. See Order webhooks.

Credits and licences

Goose, Apache-2.0.
Hermes Agent by Nous Research, MIT.
Anthropic's shopping skills from commerce-agents, Apache-2.0.

All three are used unchanged: Goose and Hermes are installed from their releases (v1.57.0 and v0.22.5) with our settings, and the skills are copied as published. A download that includes the shopping skills or Hermes's own skills carries their licence.

Something wrong on this page?