Managing Observal Agents
Execution contract
- Execute commands with a 60 second timeout.
- Use machine output by default: add
--output json whenever supported. Parse list results from items and pagination fields.
- Use
--help before acting when a path or flag is uncertain.
- Keep workflows noninteractive. Supply required fields,
--no-prompt, and confirmation flags.
- Use UUIDs or
qualified_name values returned by JSON. Never automate with row numbers.
- Prefer native
agent init, agent add, and agent build over hand-written scaffolding or custom validation.
- Verify every publish, release, pull, ownership, and lifecycle mutation.
- Never print MCP environment values, headers, tokens, or other secrets.
- 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 |
| 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
create without complete flags starts a wizard. Agents must provide all required inputs or use a file.publish --update changes the current Agent in place.release --bump creates a reviewed version. Do not use update when the user asked for a release.- Public teamspace publication may remain private with a pending visibility or listing review. Report the actual returned status.
- Pull success requires checking
files, warnings, and setup_commands. Partial setup is not success.
- A 409 is a decision point, not a generic retry signal. Read current state before choosing update or release.
Completion
Report the canonical Agent identity, resulting status and version, files changed for local operations, warnings, and the smallest next action. Verify with agent show, agent versions, or scan when the mutation response is not sufficient.
1---2name: observal-agents3description: Creates, authors, validates, publishes, updates, versions, pulls, archives, restores, transfers, and manages co-authors for Observal Agents. Use when the user wants to build or install an Agent, change an Agent definition, publish a draft, release a version, or manage Agent ownership.4---56# Managing Observal Agents78## Execution contract9101. Execute commands with a 60 second timeout.112. **Use machine output by default:** add `--output json` whenever supported. Parse list results from `items` and pagination fields.123. Use `--help` before acting when a path or flag is uncertain.134. Keep workflows noninteractive. Supply required fields, `--no-prompt`, and confirmation flags.145. Use UUIDs or `qualified_name` values returned by JSON. Never automate with row numbers.156. Prefer native `agent init`, `agent add`, and `agent build` over hand-written scaffolding or custom validation.167. Verify every publish, release, pull, ownership, and lifecycle mutation.178. Never print MCP environment values, headers, tokens, or other secrets.189. Mutations are sent once. After an uncertain transport failure, read Agent state before retrying.1920## Choose the workflow2122| User intent | Workflow |23| --- | --- |24| Find or inspect an Agent | Discover and inspect |25| Install an existing Agent into a harness | Pull and verify |26| Create a simple Agent in one call | Direct create |27| Author an Agent with components or files | Init, add, build, publish |28| Change the current listing without a new reviewed version | Update in place |29| Publish a reviewed patch, minor, or major version | Release |30| Create many Agents from a prepared file | Bulk create |31| Archive, restore, transfer, or manage co-authors | Lifecycle and collaboration |3233Read [Agent workflows](references/agent-workflows.md) completely before executing the selected workflow.3435## State rules3637- `create` without complete flags starts a wizard. Agents must provide all required inputs or use a file.38- `publish --update` changes the current Agent in place.39- `release --bump` creates a reviewed version. Do not use update when the user asked for a release.40- Public teamspace publication may remain private with a pending visibility or listing review. Report the actual returned status.41- Pull success requires checking `files`, `warnings`, and `setup_commands`. Partial setup is not success.42- A 409 is a decision point, not a generic retry signal. Read current state before choosing update or release.4344## Completion4546Report the canonical Agent identity, resulting status and version, files changed for local operations, warnings, and the smallest next action. Verify with `agent show`, `agent versions`, or `scan` when the mutation response is not sufficient.
Observal