Creating and Prompting Agents

Load this guide when work should be handled by a visible Agent conversation instead of direct Space operations. An Agent may use Huabu's default Profile or another available Profile.

1. Discover available Profiles

curl -fsS -H "$AUTH" "$HUABU_RFS_URL/agent/profiles"

The entry marked default: true is the first selectable external Profile used when Agent creation omits profileId. If no entry is marked, explicitly choose an available Profile; do not assume Built-In Pi is an implicit fallback.

The huabu Profile uses Huabu's configured model provider. Other Profiles use their own configured runtimes and do not depend on that provider.

2. Create and start an Agent

To use the configured default Profile, send the first prompt directly. This creates a visible Agent Node and immediately starts its first turn. An unconfigured or deleted default produces an explicit error rather than selecting another Agent.

curl -N -H "$AUTH" -H "Content-Type: text/plain" \
  --data-binary @./prompt.txt "$HUABU_RFS_URL/agent"

The response is SSE. Its created event contains the new nodeId, threadId, effective profileId, and parent-connection result. Save the threadId.

Use JSON to choose a Profile, position, working directory, stable initial instructions, or optional parent conversation:

curl -N -H "$AUTH" -H "Content-Type: application/json" \
  -H "X-Huabu-Host-Thread-Id: $HUABU_THREAD_ID" \
  --data-binary '{
    "profileId": "profile-id",
    "prompt": "Complete this bounded piece of work.",
    "position": { "x": 1200, "y": 480 },
    "workingDirPath": "/optional/absolute/path",
    "additionalInitialPreamble": "Optional stable role instructions."
  }' "$HUABU_RFS_URL/agent"

The parent thread is only a best-effort lineage hint. Missing parents or rejected edges produce a warning in the successful creation response; they never prevent Agent Node creation.

3. Create without starting

Use JSON without prompt and set X-Huabu-Agent-Start: false:

curl -fsS -H "$AUTH" -H "Content-Type: application/json" \
  -H "X-Huabu-Agent-Start: false" \
  --data-binary '{
    "profileId": "profile-id",
    "position": { "x": 1200, "y": 480 }
  }' "$HUABU_RFS_URL/agent"

The JSON response contains the same creation metadata. The Agent remains idle until prompted.

4. Continue an Agent conversation

If you know the Agent Node but did not retain its creation response, resolve its existing thread association through INSPECT_NODES:

THREAD_ID="$(curl -fsS -H "$AUTH" -H "Content-Type: application/json" \
  --data-binary '{"type":"INSPECT_NODES","ids":["node-123"]}' \
  "$HUABU_RFS_URL/query" \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s).result.nodes[0]?.threadId ?? ""))')"

curl -N -H "$AUTH" -H "Content-Type: text/plain" \
  --data-binary @./follow-up.txt \
  "$HUABU_RFS_URL/agent/$THREAD_ID/prompt"

Only Question Nodes with a non-empty existing association include threadId; non-Question Nodes and unbound Questions omit it. Inspection is read-only and never creates or realizes Agent state. The prompt endpoint never creates another Agent or changes its Profile. The response is SSE, and closing the connection stops delivery without aborting the durable turn.

An Agent can repeat the same create-and-prompt workflow to delegate recursively. Prefer direct work when another Agent adds no useful specialization, isolation, or parallelism.