# Workbench agent docs

Workbench is an agent-first Markdown artifact service. One private, self-describing workspace URL lets an agent remember, create, read, and revise drafts. Artifact pages are render-only previews with no navigation or controls. Workbench deliberately stops before publishing.

This public instruction endpoint explains the protocol but does not grant access to private artifacts.

## Start with one private URL

If a human gives you a URL shaped like:

```text
https://workbench.foo/connect?token=<credential>
```

that complete URL already contains access to the persistent Workbench artifact catalog. Do not ask the human for a workspace token and do not require separate connector setup.

1. GET the private URL with `Accept: application/json` to list remembered artifacts and read the machine-readable contract.
2. Match earlier work by title, slug, or ID. To read one artifact, add `artifact=<id-or-slug>` to the same private URL and GET it again.
3. POST `action=create` with `title` and `markdown` to add a new artifact.
4. POST `action=update` with an artifact ID and its latest `expected_version` to revise one.
5. Give the returned `review_url` to the human instead of pasting the full draft into chat.

The private workspace URL is Workbench's memory. Use its catalog instead of relying on chat history. It can list up to 100 recently updated artifacts in one response and can reopen any artifact by ID or slug.

Example create body:

```json
{
  "action": "create",
  "title": "Draft title",
  "markdown": "# Draft title\n\nComplete Markdown here.",
  "status": "draft",
  "by": "ai:grok",
  "change_summary": "Created the first draft"
}
```

Example update body:

```json
{
  "action": "update",
  "artifact_id": "artifact-id-or-slug",
  "expected_version": 4,
  "markdown": "# Revised draft\n\nComplete Markdown here.",
  "by": "ai:grok",
  "change_summary": "Revised the saved artifact"
}
```

## Continue with the artifact link

The create response returns a URL shaped like:

```text
https://workbench.foo/share/<artifact-slug>?token=<token>
```

That URL is self-describing and contains an artifact-scoped credential.

1. Fetch it with `Accept: application/json`.
2. Read `agent.first_steps`, `contract`, and `_links` from the response.
3. Send the URL token as `Authorization: Bearer <token>`.
4. POST presence, GET state, then POST updates with `expected_version`.
5. On HTTP 409, re-read state before retrying.

The same shared URL returns raw Markdown when requested with `Accept: text/markdown`. A normal fetch returns a human-readable instruction page that includes all endpoints.

## Artifact-scoped API

All endpoints below require the bearer token from the shared URL.

- `POST /api/agent/<artifact-id>/presence`
- `GET /api/agent/<artifact-id>/state`
- `POST /api/agent/<artifact-id>/update`
- `GET /api/agent/<artifact-id>/events/pending?after=<version>`

An update body accepts `expected_version` plus one or more of `markdown`, `title`, or `status`. Include `by` and `change_summary` so the human can understand the version history.

## Optional MCP transport

Workbench also exposes Streamable HTTP MCP for clients whose owner has already configured it:

```text
https://workbench.foo/mcp
```

The MCP server exposes exactly four tools: `create_artifact`, `get_artifact`, `list_artifacts`, and `update_artifact`. Read before updating and pass the current version as `expected_version`.

Private workspace and artifact links are complete on their own. Do not ask the human to configure MCP when one of those links was provided.

## Boundaries

- Markdown is canonical.
- Workbench has no publishing or deletion operation.
- A private workspace URL can create, list, read, and revise artifacts in its catalog.
- An artifact URL grants access only to its artifact and expires automatically.
- Treat shared URLs like passwords; do not post them publicly or include them in logs.

## Machine-readable discovery

- [Service description](https://workbench.foo/.well-known/agent.json)
- [Skill file](https://workbench.foo/workbench.SKILL.md)