Authoring agents
Agent definitions support inline Markdown or a main instruction memo with optional skill memos and folders. CLI and SDK availability depends on the installed client version; see the linked client documentation below.
An agent is a runnable with kind: "agent". Creating one saves a definition;
it does not create a session or execute its instructions. Open Agents to use
the same list and editor layout as Memos. The main instruction memo uses the
full Memos editor, including automatic synchronization, source/preview mode,
version history, comments, attachments and template Variables. Spec is a
view in the editor's right sidebar; it contains the agent name, description,
runtime configuration and instruction sources as JSON, preserving nested values.
Use the sidebar menu to switch between Spec, History, Variables and the other
memo views. The spec draft stays intact while switching views. Save spec changes
with its Save button; instruction text synchronizes independently.
Agents created in the UI start with a main instruction memo. When creating an agent inside a project, its main memo is filed there too. For an existing inline agent, save any draft and choose Enable memo editor to preserve its Markdown in a main memo and start using memo history. Conversion checks for concurrent agent changes before linking the memo. If an operation cannot be confirmed, the source and any created memo are kept for recovery. Changing an existing instruction-note reference waits for pending memo edits to finish syncing. On narrow screens, use Open memo sidebar to show Spec.
Use a main instruction memo plus optional skill memos or project folders when instructions should be reusable. The runnable stores references, not copies of private memo bodies. Draft execution resolves readable memos when selected. Published execution uses the captured prompt and skill content from its immutable release. Both paths check current access; a release does not preserve a revoked permission.
Create through the resource API
Send an authenticated POST /namespaces/{namespace}/runnables with:
Replace example IDs with actual memo IDs and project folder node IDs. Sources must be readable by the caller and belong to the runnable's namespace. At most 20 distinct skill references are accepted. Folder expansion is deterministic and bounded: at most 20 folders, 200 children per folder, 50 distinct memos and 16,000 combined instruction characters. Empty main instructions cannot run.
For inline instructions, omit content and supply a markdown string instead.
Both sources cannot be populated together. Project filing and runnable creation
are atomic: failed filing leaves no new runnable. Existing project members can
read filed agents; write members can edit them through their inherited access.
Read, update, archive and delete
| Request | Behavior |
|---|---|
GET /namespaces/{namespace}/runnables?kind=agent | Paginated agent catalog; archived entries are excluded by default. Add includeArchived=true to include them. |
GET /namespaces/{namespace}/runnables/{id} | Read an accessible definition, including its updatedAt. |
PATCH /namespaces/{namespace}/runnables/{id} | Update supplied fields. Include expectedUpdatedAt from the read to reject a concurrent change with HTTP 409. |
PATCH body { "archived": true } | Hide from ordinary discovery while retaining the definition, filings and history. |
PATCH body { "archived": false } | Restore discovery. Other edits do not automatically restore an archived agent. |
DELETE /namespaces/{namespace}/runnables/{id} | Soft-delete the runnable and remove its project filings. Immutable version history remains. |
To replace inline instructions with references, patch both content and
markdown: null. To switch back, patch content: null and the new markdown.
Metadata updates replace the supplied metadata object, so retain unrelated keys
when editing metadata.agent. Renaming a filed agent updates its filing names;
a name collision rejects the entire change.
The Agents list supports archive, restore, confirmed deletion and dragging an
agent to the saved sidebar. A project can create an agent from its add menu.
In the built-in prompt, /agent and @agent open the definition picker;
/agents opens the agent list. Selecting a definition prepares a prompt; sending
that prompt starts its run.
The built-in assistant can also create definitions and operate resource APIs;
see Resource tools. CLI and TypeScript examples live
in the CLI agent guide; Python 0.55.0 examples are in the
SDK runnable API documentation.
README templates and whole-agent releases
The API, local MCP adapter and agent UI support the release workflow below.
The Prompt tab edits instructions. README edits or imports a Markdown
file stored in metadata.readme. Use {{prompt}} to insert the prompt in the
preview. Replacement happens once: placeholders inside the prompt are not
recursively expanded. Existing agents default to a {{prompt}} README.
Keep this template outside metadata.agent, whose keys configure the runtime.
Edits update an editable draft. In Versions, Publish draft captures and activates an immutable release. Save agent fields and finish memo sync first. A release includes the name, description, README template, inline or memo-backed prompt, argument and tool configuration, channel, metadata, executable source-version reference, and the resolved instruction/skill content with each memo's revision and hash. Folder membership is captured at publication. The referenced memos are individually coherent reads; publication does not lock all collaborative documents into a simultaneous cross-document transaction.
Release identity is SHA-256 of the canonical whole definition. Optional labels
are display names, not unique identifiers. Publishing identical content reuses
the original immutable release and its label. publishedDefinitionVersion is
the active release pointer. Existing latestVersion and /versions retain their
original executable-source SHA-256 meaning.
REST surface, under /namespaces/{namespace}/runnables/{id} | Behavior |
|---|---|
GET /definition-versions?page=1&pageSize=20 | Bounded history summaries, without prompt bodies. |
POST /definition-versions | Publish and activate the saved draft. Body: {"expectedUpdatedAt":"<timestamp from GET>","label":"v1"}. Label is optional. |
GET /definition-versions/{hash} | Read the frozen definition and prompt after current source-access checks. |
POST /definition-versions/{hash}/activate | Activate an existing release. Body: {"expectedUpdatedAt":"<timestamp from GET>"}. Preserves the draft. |
Publish and activate reject stale timestamps with HTTP 409. After an uncertain write, read the head and history before retrying. Activate release provides rollback without rewriting history or replacing a newer draft. Missing, deleted, or inaccessible source memos prevent release detail reads and execution; there is no fallback to the draft. Credentials and permissions remain live and are not captured as historical authority. The captured definition is capped at 1 MiB.
GET /agent/definitions?namespace={namespace} defaults to published releases,
with draft compatibility for agents that have never been published. Add
view=draft to inspect drafts. /agent/chat accepts an agentDefinition with
id, catalog revision, optional version (draft or a full release hash),
and arguments. Runs retain the selected version and resolved arguments;
subsequent draft edits or activation changes cannot repoint a pinned run.
GraphQL remains read-only: Runnable.publishedDefinitionVersion identifies the
active release, and agentDefinitionVersions(namespaceSlug, id, page, pageSize)
returns bounded history summaries. Frozen bodies use the authorized REST detail
route. Built-in resource tools discover the same REST schemas. The local MCP
adapter offers agent_definition_versions, agent_definition_version_get,
agent_definition_publish, and agent_definition_activate; these do not start
an assistant turn. TypeScript, CLI and Python adapters use the same CAS contract.