Managing Observal Agents

Execution contract

1. Execute commands with a 60 second timeout.
2. Use machine output by default: add --output json whenever supported. Parse list results from items and pagination fields.
3. Use --help before acting when a path or flag is uncertain.
4. Keep workflows noninteractive. Supply required fields, --no-prompt, and confirmation flags.
5. Use UUIDs or qualified_name values returned by JSON. Never automate with row numbers.
6. Prefer native agent init, agent add, and agent build over hand-written scaffolding or custom validation.
7. Verify every publish, release, pull, ownership, and lifecycle mutation.
8. Never print MCP environment values, headers, tokens, or other secrets.
9. Mutations are sent once. After an uncertain transport failure, read Agent state before retrying.

Choose the workflow

User intent	Workflow
Find or inspect an Agent	Discover and inspect
Install an existing Agent into a harness	Pull and verify
Create a simple Agent in one call	Direct create
Customize an approved Agent without changing its source	Fork and edit
Author an Agent with components or files	Init, add, build, publish
Change the current listing without a new reviewed version	Update in place
Publish a reviewed patch, minor, or major version	Release
Create many Agents from a prepared file	Bulk create
Archive, restore, transfer, or manage co-authors	Lifecycle and collaboration

Read Agent workflows completely before executing the selected workflow.

State rules