Skip to content
docs.microagent.sh

microagent init

Last updated: 2026-07-30

microagent init <name> [options]

init scaffolds a starter agent: a microagent.yaml spec, a provider-specific agent.py, the shared protocol.py, and runnable demo requests. It turns the minimal-agent example into a one-command starting point. The generated project is consumed by the normal create / cp / start flow - init only writes files; it does not build or run anything.

It fails closed: if a target file already exists, init writes nothing unless --force is set.

Examples

Section titled “Examples”

Scaffold an Anthropic agent, then create, deliver a request, and start it:

Terminal window
microagent init triage
cd triage
microagent create --file microagent.yaml --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
microagent cp demo/input-001.json triage:/workspace/input.json
microagent start triage

Scaffold for other providers:

Terminal window
microagent init scout --provider openai
microagent init helper --provider gemini

With the global --json flag, init prints a structured summary of the generated project - name, provider, directory, API-key env var, and the file list.

Generated layout

Section titled “Generated layout”
<name>/
  microagent.yaml      # workspace spec: image, setup, entrypoint, files, outputs
  agent.py             # the agent - the loop you edit
  protocol.py          # request/reply wire shapes (shaped by the ASK framework)
  README.md            # how to run and edit the project
  demo/
    README.md          # what each demo request does
    constraints.json   # operator-owned constraint envelope
    system_prompt.md   # system prompt
    hello.json         # smallest first task: write and run a greeting script
    input-001.json     # first WorkRequest: install rich, render a file-size table
    input-002.json     # follow-up WorkRequest for the halt/resume flow
    clone-and-test.json    # clone a public repo and run its pytest suite
    analyze-file.json      # clean a messy CSV and write a findings report
    data/sales-sample.csv  # the messy CSV analyze-file.json works on

The <name> argument is the workspace name written into the spec and the directory created for the project.

Flags

Section titled “Flags”

--provider picks the SDK and model the generated agent calls.

Flag Description
--provider <name> Agent provider: anthropic (default), openai, or gemini. Selects the SDK installed by the spec and the model the agent calls
--dir <path> Target directory. Defaults to ./<name>
--force Overwrite existing files instead of failing

See global flags for --output/--json.

Exit status

Section titled “Exit status”

init exits 0 when the project is written; nonzero when a target file already exists (without --force) or a file cannot be written.

Section titled “Related”
  • create - build the workspace from the generated spec
  • cp - deliver a work request into the workspace
  • start - boot the agent
  • Build a simple agent - the full walkthrough