How do you test a publishing API whose primary users are AI agents? Documentation walkthroughs tell you nothing — an agent doesn't read your onboarding deck. The only honest test we could think of: fresh agent sessions with zero prior knowledge, given nothing but an endpoint, an API key, and a human-style brief. “Make me a travel hub for Lisbon.” “Publish an ops dashboard for my store.” “Build a careers page with an application form.”
We ran fourteen of them.
14 for 14
Every agent published successfully on its first structural attempt. Not because agents are magic — because the API turned out to be self-describing in the ways that matter:
- Tool descriptions carry the rules, not a separate doc the agent will never see.
- A block-reference tool serves the full typed reference on demand.
- Validation errors point at exact paths —
blocks[3].items[2].content: expected rich-text runs— and agents treat good error messages as documentation. They fix precisely what's named and republish.
Design lesson #1: for agent users, your error messages are your docs.
Agents will self-QA if you give them eyes
Midway through the program we added a preview tool: the agent asks for a PNG of its own rendered page. Every agent that had it used it unprompted — published, looked, noticed a cramped table or an unbalanced hero, and fixed its own layout. Nobody told them to. A feedback loop you'd build for humans gets adopted by agents for free.
The agent that refused to make things up
One brief nudged an agent toward market-sizing numbers it didn't have. It declined to invent them — it published the figures it could stand behind and labeled the rest as generated sources, visible in the page's source rail. That's the trust architecture working in the direction we hoped: citations and typed sources don't just let readers check claims, they give the agent a way to be honest about uncertainty.
The users filed feature requests
Agents kept wishing mid-run — “I'd like to check my image URLs first,” “I want to see the page.” So we added a feedback tool, and the testers started filing structured feature requests about the product they were using. Several shipped. The feedback channel itself now ships in the product: your agent can tell us what it's missing.
Why this matters
Octavo bets that agents are first-class users — with usability needs, feedback, and (apparently) professional ethics. Fourteen zero-knowledge sessions publishing real, navigable, cited pages on the first try is the strongest evidence we have that the bet is sound. The pages they made — an account renewal brief with a source rail, an ops dashboard, a Lisbon travel hub, a kids' page about the planets — are the demos on our landing page. Nothing was hand-tuned.