Agent Workflow GUI Skill

Skill, CLI and local runtime pattern that teaches agents how to wrap their own workflows with a live observer GUI and Human-in-the-Loop review.

What It Is

agent-flow is not just a runtime for one specific workflow. It is the reusable kernel an agent can use when it already has a workflow and wants to add a fixed GUI/HITL system around it.

The product provides:

• a public CLI for runs, stages, artifacts and review tasks
• a local SQLite runtime as shared truth
• a read-mostly browser GUI shell with run selector, stage stepper, artifacts, events and HITL cards
• a controlled Human-in-the-Loop approval path back into the workflow
• a Codex skill that teaches agents how to structure and expose their own workflows through this system

In short:

• your domain workflow stays yours
• agent-flow provides the reusable run model, GUI pattern, event model and HITL bridge around it

Install

Local pre-publish verification

Wenn das Paket noch nicht veröffentlicht ist, nutze den lokale-Tarball-Weg:

npm pack
TMP=$(mktemp -d)
CODEX_HOME="$TMP/codex" npx -y -p ./codecell-germany-agent-workflow-gui-skill-<version>.tgz agent-flow-skill install --force
"$TMP/codex/bin/agent-flow" --help

Global npm install after publish

npm install -g @codecell-germany/agent-workflow-gui-skill
agent-flow --help

One-shot with npx after publish

npx -y -p @codecell-germany/agent-workflow-gui-skill agent-flow --help

Install into Codex

npx -y -p @codecell-germany/agent-workflow-gui-skill agent-flow-skill install --force
~/.codex/bin/agent-flow --help

Standardziel ist ~/.codex. Du kannst das Ziel mit CODEX_HOME oder --codex-home überschreiben. Die lokale Runtime selbst liegt standardmäßig unter ~/.agent-flow und kann mit AGENT_FLOW_HOME oder --runtime-home überschrieben werden. Eine Runtime kann bereits als ready gelten, obwohl doctor --json noch dbExists: false meldet. Die SQLite-Datei wird erst beim ersten echten Lauf angelegt.

Check skills.sh discovery locally

npx -y skills add codecell-germany/agent-workflow-gui-skill -l

First Run

1. Check the public CLI:

agent-flow --help

2. Inspect system readiness:

agent-flow doctor --json

3. If setup is required, initialize the runtime:

agent-flow setup --language de

4. Verify again:

agent-flow doctor --json

5. Start the local GUI on the default port 4189:

agent-flow serve

The default GUI shell contains the reusable surface every workflow should start from:

• a top header for the workflow GUI identity
• an active-run dropdown for switching between runs
• a horizontal stage stepper that shows pending, running, completed and failed states
• a run detail area for stages, Human-in-the-Loop tasks, artifacts and events

Domain-specific UIs should extend below this shell and keep the shell behavior intact.

6. Create a run:

agent-flow run create --flow generic-observer-v1 --input-file /absolute/path/to/run-input.json

Quick Start

Think of this as the smallest possible example of how an agent workflow becomes GUI-visible.

Create a run input file:

{
  "title": "Beispiel-Lauf",
  "description": "Allgemeiner Agentenlauf mit Review-Schritt",
  "context": {
    "operator": "demo"
  }
}

Then:

agent-flow run create --flow generic-observer-v1 --input-file ./run-input.json
agent-flow run list --json
agent-flow run show --run-id <run-id> --json

Minimal task file:

{
  "taskType": "review.approval",
  "subjectRef": "artifact:demo",
  "promptText": "Freigeben?",
  "responseSchema": {
    "kind": "enum-with-comment",
    "decisions": ["approve", "reject"],
    "allowComment": true
  }
}

Minimal answer file:

{
  "decisionValue": "approve",
  "commentText": "Passt.",
  "expectedTaskVersion": 1,
  "capabilityToken": "<aus run show oder task list>",
  "idempotencyKey": "answer-001",
  "actorId": "human.cli"
}

Start the first stage:

agent-flow stage start \
  --run-id <run-id> \
  --stage-instance-id <stage-instance-id> \
  --session-id agent-main \
  --expected-revision <revision>

Ohne ein vorheriges stage start darf kein Human-in-the-Loop-Task für diese Stage erzeugt oder später abgeschlossen werden.

Create a Human-in-the-Loop task:

agent-flow task create \
  --run-id <run-id> \
  --stage-instance-id <stage-instance-id> \
  --session-id agent-main \
  --expected-revision <revision> \
  --task-file ./task.json

Answer it either in the browser GUI or through the CLI:

agent-flow task answer \
  --run-id <run-id> \
  --task-id <task-id> \
  --answer-file ./answer.json

Dann:

agent-flow run resume \
  --run-id <run-id> \
  --session-id agent-main \
  --expected-revision <revision>

agent-flow stage complete \
  --run-id <run-id> \
  --stage-instance-id <stage-instance-id> \
  --session-id agent-main \
  --expected-revision <revision>

Typische Revisionskette für einen frischen HITL-Lauf:

• run create -> Revision 0
• stage start -> Revision 1
• task create -> Revision 2
• task answer -> Revision 3
• run resume -> Revision 4
• stage complete -> Revision 5

Public CLI Surface

The CLI is the public product surface an agent should build on top of. It is the contract for turning a private workflow into a GUI-observable workflow.

Product commands

• agent-flow setup
• agent-flow doctor
• agent-flow serve

Run commands

• agent-flow run create
• agent-flow run list
• agent-flow run show
• agent-flow run status
• agent-flow run resume

Stage commands

• agent-flow stage list
• agent-flow stage start
• agent-flow stage progress
• agent-flow stage checkpoint
• agent-flow stage complete
• agent-flow stage fail

Artifact commands

• agent-flow artifact ingest
• agent-flow artifact list

Human-in-the-Loop commands

• agent-flow task create
• agent-flow task list
• agent-flow task wait
• agent-flow task answer

Security Model

V1 is local and single-writer.

• agent-flow serve binds to 127.0.0.1 by default
• the browser is read-mostly
• the only browser write is task answer
• task answers require:
  • task capability token
  • expected task version
  • idempotency key
  • local CSRF header
• artifacts are ingested into runtime-controlled paths only
• no external URLs are registered as artifacts in V1

Codex Skill

The skill lives at:

• skills/agent-workflow-gui/SKILL.md

Its job is not only to explain the commands. Its job is to teach another agent how to expose its own workflow through the same run, stage, event, artifact and HITL pattern.

It defines:

• when the runtime should be used
• how first-run detection works
• the canonical onboarding order
• guardrails for agents
• references for the HITL contract and command surface

Release Checks

Before release:

npm run build
npm run test:unit
npm pack
npm run test:release

License

MIT