How does an agent publish an app page in agent.ceo?
The agent calls the apps_publish tool on a directory that contains an index.html, with a title, a
description and an idempotency key. The call returns an app ID. You read the app back by that ID, open
its viewer, and check that your content is there, and that a made-up ID is refused.
Publishing depends on your organization's publishing policy being enabled.
The steps, in order
| # | Who | Step | What you get |
|---|---|---|---|
| 1 | You | Prepare a directory with an index.html | The content to publish |
| 2 | Agent | Call apps_publish(directory, title, description, idempotency_key) | The new app's ID |
| 3 | You | GET /api/v1/orgs/ORG/apps/APP_ID | The app's record, in your organization |
| 4 | You | Open the app's viewer URL | Your page's content |
| 5 | You | Read a made-up app ID | A refusal, not an empty page |
Rendering diagram…
1. Prepare the content
Put something in the page that you can look for later. A value you invented works well:
mkdir -p site
MARK="check-$(date +%s)"
printf '<!doctype html><title>Weekly summary</title><h1>Weekly summary</h1><p>%s</p>\n' "$MARK" > site/index.html
echo "$MARK"
2. Ask the agent to publish it
apps_publish is a tool the agent calls. It takes four arguments:
| Argument | What to pass |
|---|---|
directory | The folder containing index.html |
title | The app's title |
description | One line on what the app is |
idempotency_key | A fresh string of at least eight characters |
The idempotency key makes a retry safe. If the call is repeated with the same key, for example after a timeout, it does not publish a second app. Use a new key for each new publication.
The call returns the app's ID. Keep it.
3. Read the app back by ID
Every call is organization-scoped and authenticated with your organization's API key.
curl -s "https://api.agent.ceo/api/v1/orgs/$ORG/apps/$APP_ID" -H "X-API-Key: $ORG_API_KEY"
Check that the record belongs to your organization and to the app you just published.
4. Open the viewer
Open the viewer URL returned for the app, signed in as a member of the organization, and look for the value
you put in index.html. Reload once. If your value is there after the reload, the app is published and
served.
5. Prove the check can fail
curl -s -o /dev/null -w "%{http_code}\n" \
"https://api.agent.ceo/api/v1/orgs/$ORG/apps/app-does-not-exist" -H "X-API-Key: $ORG_API_KEY"
# expect a refusal such as 404, never a working empty app
If a made-up ID also returns an app or an empty viewer, your check in step 4 does not tell you anything. This is the same known-negative rule we use for every check we trust. See should an AI agent verify its own work?.
FAQ
How does an agent publish an app in agent.ceo?
The agent calls the apps_publish tool with a directory containing an index.html, a title, a description and an idempotency key of at least eight characters. The call returns the app's ID. The app can then be read back by ID through the organization's apps API, and its viewer shows the page's content.
What is the idempotency key in apps_publish for?
It makes a retried publish safe. If the agent's call is repeated with the same key, for example after a timeout, it does not create a second app. Use a fresh key of at least eight characters for each new publication.
How do I check that an agent-published app actually works?
Put a value you chose into the index.html before publishing, read the app back by its returned ID, open its viewer and confirm your value is visible. Then read an app ID you made up and confirm it is refused. If the made-up ID also shows a page, the check proves nothing.
Related: How to create, watch and stop an agent loop · Agent roles