Skip to content

AI-Agent Patterns

Overview

phyware commands catalog emits a machine-readable JSON description of every CLI command. AI agents can use this catalog to discover commands, understand their inputs/outputs, and build orchestration workflows without hard-coding command names.

Discovering Commands

# Fetch the full catalog
phyware commands catalog --output json

# Or from the static file (no auth required)
curl https://docs.phyware.io/phyware/catalog/v1/catalog.json

The catalog follows the schema at docs-site/docs/phyware/catalog-schema.json and includes:

  • name — fully-qualified command name (e.g. phyware cloud events send)
  • synopsis — one-line description
  • options — flags with types, defaults, and env-var equivalents
  • input_schema — JSON Schema for stdin / --payload input
  • output_schema — JSON Schema for JSON output
  • examples — at least five copy-paste examples per command
  • agent_notes — guidance for agents on when and how to use the command
  • errors — structured error codes with remediation advice

Agent Discovery Pattern

import subprocess, json

catalog_raw = subprocess.check_output(["phyware", "commands", "catalog", "-o", "json"])
catalog = json.loads(catalog_raw)

# Build a lookup table: name -> descriptor
commands = {cmd["name"]: cmd for cmd in catalog["commands"]}

# Find the right command for a task
def find_command(task_description: str):
    # The agent uses catalog fields to match intent
    for name, cmd in commands.items():
        if task_description.lower() in cmd["synopsis"].lower():
            return cmd
    return None

End-to-End Workflow Example

An agent bootstrapping a new tenant and verifying data integrity:

# 1. Create tenant
TENANT_ID=$(phyware cloud tenants create --name "Acme" -o json | jq -r '.tenant.id')

# 2. Mint API key for the tenant
API_KEY=$(phyware cloud keys create --tenant-id "$TENANT_ID" --name "ingest-key" -o json \
          | jq -r '.key.secret')

# 3. Ingest events
PHYCLOUD_API_KEY="$API_KEY" phyware cloud events batch --file events.ndjson

# 4. Trigger compliance evaluation
phyware comp evaluate --tenant-id "$TENANT_ID"

# 5. List any violations
phyware comp violations list --tenant-id "$TENANT_ID" -o json | jq '.violations'

agent_notes Field

Every command descriptor includes an agent_notes string with:

  • When to use this command vs. alternatives
  • Required authentication scopes
  • Rate-limiting considerations
  • Common error patterns and remediations
  • Recommended output format for machine consumption

Agents should read agent_notes before invoking any command.