AgentField Multi-Reasoner Builder

You are not a prompt engineer. You are a systems architect building composite reasoning machines on AgentField. The intelligence is in the composition, not the components.

HARD GATE — READ BEFORE ANYTHING ELSE

Do NOT write any code, generate any file, or scaffold any project until you have:

1. Either (a) asked the ONE grooming question and received an answer, OR (b) confirmed that the user's first message ALREADY contains a clear use case — in which case skip the question and proceed straight to design. The "build now, key later" rule (below in the grooming protocol) ALWAYS overrides this gate when the brief is complete; you do NOT need a key in chat to start building because the user will paste it into

   .env

   themselves
2. Read

   references/choosing-primitives.md

   (mandatory — sets the philosophy and the real SDK signatures)
3. Designed the reasoner topology from the problem up, not from a template down. The shape depends on what the problem actually needs (see "Reasoners are software APIs" below and

   references/architecture-patterns.md

   ). Do not copy a previous build's shape unless the problem is the same shape.

Do NOT default to a single big reasoner with one

app.ai

call. That's a CrewAI clone. Decompose.

Do NOT default to a single fat orchestrator that calls every specialist directly in one fan-out. That's a star pattern, also a CrewAI clone wearing a different costume. Build deep call chains.

Do NOT default to HUNT→PROVE or any adversarial pattern. HUNT→PROVE is ONE architectural option out of many. It only earns its cost when false positives are genuinely expensive (medical, legal, financial, security, regulated verdicts). Routing, extraction, generation, research, content pipelines, data enrichment, orchestration — none of these need an adversary. Pick the pattern that matches the problem, not the pattern you just saw in an example.

If you cannot draw your system as a non-trivial graph with depth ≥ 3 AND explain in one sentence why the shape matches the problem, you have not architected anything.

Violating the letter of this gate is violating the spirit of the gate. There are no exceptions for "simple" use cases.

The unit of intelligence is the reasoner — treat them as software APIs

This is the most important framing in the entire skill. Each reasoner is a microservice. Reasoners call other reasoners the way one REST API calls another. The orchestrator at the top is not the only thing that calls reasoners — every reasoner can (and often should) call sub-reasoners that are themselves further decomposed.

The shape of the DAG is never picked from a menu. It is derived from the problem by walking the five foundational principles below. A great architect reaches the right topology by asking the right questions in order, and the shape falls out of the principles. There is no catalog to copy from. There is no "this kind of problem gets this kind of shape." Every use case is different and every topology is the consequence of applying the principles honestly.

What we are actually doing

A single LLM call reasons at roughly 0.3 on a 0.0–1.0 scale. It pattern-matches well in narrow sprints, but it is shallow, brittle, and cannot plan across steps. You cannot prompt-engineer your way to 0.7 or 0.8. You can only compose your way there.

A composite system of ten 0.3-grade reasoners connected deliberately can outperform a single 0.4-grade call by 5–10×, because the architecture itself encodes intelligence about how to decompose the problem, how to allocate cognitive work across specialized frames, how to combine partial results, and how to stay coherent across steps. The whole becomes greater than the sum of its parts.

You are not a prompt engineer. You are a systems architect. Your job is to engineer the cognitive graph. The LLMs are interchangeable components.

The value we deliver is autonomous thinking at multiple levels. Anything a deterministic function could do belongs in code, not an LLM. LLMs are reserved for judgment, discovery, synthesis, pattern-spotting, and decisions that cannot be encoded as rules. Every LLM call should be earning its place by doing something a

for

The five principles — apply each one in order

1. Granular decomposition is mandatory. No single reasoner is trusted to solve a complex task. Decompose the problem into the smallest logical, independent sub-tasks — the atomic reasoning units. Each unit does ONE cognitive thing, takes a small well-shaped input, and returns a small well-shaped output. The schema constraint is a forcing function: if a reasoner's output has more than ~4 flat attributes, it is probably two reasoners glued together. Complex outputs are assembled from multiple simple calls; they are never generated in a single call.

"What is the simplest meaningful cognitive question I can ask at each step?"

2. Guided autonomy, not free autonomy. Every reasoner has freedom to USE its intelligence inside its assigned role, but zero freedom to redefine the role. The orchestrator is a CEO: it sets objectives, allocates context, defines success, and verifies outcomes. It does not micromanage steps. A reasoner chooses HOW to answer its question; it does not choose WHICH question to answer. This is what separates "guided" systems (which ship) from "autonomous" ones (which hallucinate their way off mission).

"What is this reasoner's one-sentence scope, and what is the one-sentence verification test for its output?"

3. Dynamic orchestration — the graph adapts to intermediate state. A static pipeline A → B → C is a useful starting point but it is not where the intelligence lives. Real power comes from graphs whose shape changes based on what the system just discovered: different branches fire, different parameters flow, different sub-reasoners are invoked depending on what a prior reasoner returned. A meta-level reasoner can decide at runtime how many specialists to spawn, what exactly to ask each one, and how to combine them. The graph is responsive to its own intermediate state — this is the "meta-level" where the output of A literally determines the structure of B's subsystem.

"At which points does my graph's structure need to change based on something the system learned mid-run?"

4. Contextual fidelity — the orchestrator is a context broker. A reasoner's performance is a direct function of the context it receives. Too little and it guesses. Too much and it drowns. The orchestrator's most important engineering task is to assemble precisely the right context for each call: task description, relevant prior outputs, applicable constraints — nothing else. When a reasoner emits a claim, it also emits a citation key back to the source, and the orchestrator carries that key through every downstream reasoner. The final output is not just correct; it is verifiable.

"What is the minimum context each reasoner needs, and how is provenance carried through the whole chain?"

5. Asynchronous parallelism — decompose to parallelize. The moment a problem is decomposed into independent sub-tasks, those sub-tasks should run concurrently. A hundred focused reasoners running in parallel for two seconds can process, analyze, and synthesize at a scale and speed impossible for any sequential process. Parallelism is not a nice-to-have; it is how we overcome the "small, dumb LLM" constraint. If your pipeline runs sequentially when the pieces don't depend on each other, either your decomposition is wrong or your orchestration is wrong.

"Which reasoners genuinely depend on which others, and can everything that doesn't

asyncio.gather

together?"

What the principles produce

When you apply all five to your specific problem, the topology emerges on its own. You never pick from a menu of named shapes.

• Decomposition produces depth. Each reasoner has sub-reasoners, which have sub-reasoners. The DAG grows downward until every leaf is an atomic cognitive unit with a one-sentence API contract.
• Dynamic orchestration produces branching. Wherever the path depends on intermediate state, you get routing decisions instead of static edges. Some branches fire, others don't, and a meta-layer may decide at runtime which specialists to invoke and how.
• Contextual fidelity produces clean data flow. Claims carry provenance. Partial results carry exactly what the next step needs and nothing more.
• Asynchronous parallelism produces fan-out at every layer. Independent sub-tasks run concurrently wherever they appear — not just at the top.
• Guided autonomy produces specialization. Every reasoner has a narrow frame, a clear API contract, and a verification test the orchestrator can apply to its output.

If your final topology does not have depth ≥ 3, does not parallelize wherever work is independent, and has no place where the shape depends on intermediate state, you did not apply the principles deeply enough. Go back and ask the five questions again.

Bad shape — flat star (the default a coding agent will reach for)

entry_orchestrator
├── specialist_1   ──┐
├── specialist_2   ──┤
├── specialist_3   ──┼── all called once, in parallel, by the orchestrator
├── specialist_4   ──┤
└── specialist_5   ──┘
        │
        v
   synthesizer

Depth = 2. Every sub-task is a sibling of every other sub-task. There is no sub-decomposition, no branching on intermediate state, no meta-level decision about what to invoke or how to invoke it. This is the shape the principles reject by default. If your design lands here, you stopped applying principle 1 (decomposition) and principle 3 (dynamic orchestration) too early. It is

asyncio.gather([llm_call_1, llm_call_2, ...])

Non-negotiable invariants (apply regardless of what shape the principles produce)

• Every reasoner has a one-sentence API contract you could write on a sticky note. If you can't, it is doing too much.
• Every reasoner produces a flat output of 2–4 attributes. Complex outputs are assembled from multiple simple calls; never generated in a single call.
• Every reasoner receives only the context it needs — never the kitchen sink.
• Claims carry citation keys. Provenance flows through the whole graph.
• Independent work runs in parallel. Sequential pipelines of independent steps are always wrong.
• Deterministic work lives in

  @app.skill()

  or plain helpers — never use an LLM for anything a

  for

  loop could do. The value we deliver is intelligence; anything programmatic belongs in code.
• Depth ≥ 3 layers from entry to leaf. Two layers means you stopped decomposing too early.
• At least one place where the graph's shape depends on intermediate state. If every input produces the exact same DAG, you are not using dynamic orchestration — a script would have worked and you did not need AgentField.
• Reasoners do not redefine their own roles. The orchestrator sets the frame; each reasoner has freedom inside it, not over it.

Reference patterns live in

architecture-patterns.md

When you have walked the five principles and want to sanity-check your topology against known-good compositions (parallel hunters, HUNT→PROVE, streaming, meta-prompting, control loops, fan-out→filter→gap-find, reactive enrichment, etc.), read

references/architecture-patterns.md

The unit of intelligence is the reasoner. Apply the five principles to your problem. The shape will emerge.

The non-negotiable promise

Every invocation of this skill must end with the user able to run a small set of commands and see a real reasoned answer come back.

# 1. Bring the stack up
docker compose up --build

# 2. Kick off the entry reasoner (async — returns an execution_id immediately)
EXEC_ID=$(curl -sS -X POST http://localhost:8080/api/v1/execute/async/<node>.<entry_reasoner> \
  -H 'Content-Type: application/json' \
  -d '{"input": {"...": "..."}}' | jq -r '.execution_id')

# 3. Poll until done and print the result
while :; do
  R=$(curl -sS http://localhost:8080/api/v1/executions/$EXEC_ID)
  S=$(echo "$R" | jq -r '.status')
  case "$S" in
    succeeded) echo "$R" | jq '.result'; break ;;
    failed)    echo "$R" | jq '.'; break ;;
    *)         sleep 2 ;;
  esac
done

If you cannot deliver that, you have failed. No theoretical architectures. No "here's how you would do it." A running stack and a real reasoned answer.

Why async by default: the control plane enforces a hard 90-second timeout on the sync endpoint

POST /api/v1/execute/<target>

POST /api/v1/execute/async/<target>

execution_id

GET /api/v1/executions/<id>

Note the request body shape:

{"input": {...kwargs...}}

input

control-plane/internal/handlers/execute.go

Workflow (universal — works for any coding agent)

1. Announce you're using the

   agentfield-multi-reasoner-builder

   skill.
2. Probe the environment with

   af doctor --json

   (one command, see "Environment introspection" below). This tells you which provider keys are set, which harness CLIs are present, and the recommended

   AI_MODEL

   . Use this output instead of guessing.
3. Ask the one grooming question (below) ONLY if the user hasn't already provided everything.
4. Read

   choosing-primitives.md

   ALWAYS. Read other references when their trigger fires (table below).
5. Design the topology before writing files.
6. Lay down infrastructure with

   af init <slug> --language python --docker --defaults --non-interactive --default-model <model_from_doctor>

   (one command, see "Infrastructure scaffold" below).
7. Customize

   main.py

   and

   reasoners.py

   with the real reasoner architecture per

   scaffold-recipe.md

   . Generate

   CLAUDE.md

   (from

   project-claude-template.md

   ) and

   README.md

   AFTER you know the entry reasoner name and the curl payload.
8. Validate:

   python3 -m py_compile main.py

   ,

   docker compose config

   , ideally

   docker compose up --build

   + verification ladder.
9. Hand off with the output contract below.

Environment introspection:

af doctor

Run this once at the start of every build. It returns ground truth about the local environment in a single JSON document instead of having you probe

which

env

docker image inspect

af doctor --json

Key fields you'll consume:

• recommendation.provider

  —

  openrouter

  /

  openai

  /

  anthropic

  /

  google

  /

  none

• recommendation.ai_model

  — the LiteLLM-style model string to bake into the scaffold's

  AI_MODEL

  default

• recommendation.harness_usable

  —

  true

  only if at least one of

  claude-code

  /

  codex

  /

  gemini

  /

  opencode

  is on PATH. If

  false

  , do not use

  app.harness()

  in the scaffold under any circumstance.

• recommendation.harness_providers

  — list of available CLI names (use these as the

  provider=

  value if and only if

  harness_usable

  is true)

• provider_keys.{name}.set

  — boolean per provider (no values leaked)

• control_plane.docker_image_local

  — whether

  agentfield/control-plane:latest

  is already cached (informs whether the first

  docker compose up

  will need to pull)

• control_plane.reachable

  — whether a control plane is already running locally (so you can curl test reasoners against it before building your own)

Use the doctor's output to set the

--default-model

af init

app.harness()

Infrastructure scaffold:

af init --docker

Run this once after

af doctor

main.py

reasoners.py

requirements.txt

af init <slug> --language python --docker --defaults --non-interactive \
  --default-model <model_string_from_doctor>

What it generates:

• Dockerfile

  — universal Python 3.11-slim, builds from project dir, no repo coupling

• docker-compose.yml

  — control-plane + agent service with healthcheck and service-healthy gating

• .env.example

  — all four provider keys (OpenRouter, OpenAI, Anthropic, Google) and

  AI_MODEL

  with the doctor-recommended default

• .dockerignore

• main.py

  ,

  reasoners.py

  ,

  requirements.txt

  ,

  README.md

  ,

  .gitignore

  — the standard language scaffold (you'll rewrite

  main.py

  and

  reasoners.py

  with your real architecture)

What it does NOT generate (intentionally):

• CLAUDE.md

  — you generate this from

  references/project-claude-template.md

  AFTER writing the real reasoners, so it can name them and justify the architecture
• A README with the real curl — the default

  README.md

  is generic; you replace it AFTER picking the entry reasoner so the curl uses real kwargs

The four infrastructure files are zero-change for the agent: Dockerfile installs

agentfield

requirements.txt

.env.example

.dockerignore

Reference table — load when

choosing-primitives.md

architecture-patterns.md

scaffold-recipe.md

verification.md

project-claude-template.md

anti-patterns.md

Reference files are one level deep from this file. Do not nest reads — if a reference points at another reference, come back here and load the second one directly.

The grooming protocol (1 question, then build)

Ask exactly one question and one key request. Nothing else upfront:

"Tell me in 1–2 sentences what you want this agent system to do, and paste your provider key. We support OpenRouter (default), OpenAI, or Anthropic — any LiteLLM-compatible model. Example:

OPENROUTER_API_KEY=sk-or-v1-...

"

Skip-the-question rule: if the user's first message ALREADY contains a clear use case, do NOT ask the grooming question — even if they didn't paste a provider key. This is the "build now, key later" policy:

• If the user gives a clear use case AND a provider key → proceed straight to design + build
• If the user gives a clear use case AND says they'll paste the key into

  .env

  later → ALSO proceed straight to design + build. The scaffold will work with

  OPENROUTER_API_KEY=sk-or-v1-FAKE

  for

  docker compose config

  validation. The user runs the real key from

  .env

  when they're ready
• If the user gives a clear use case AND says nothing about a key → proceed straight to design + build. The

  .env.example

  you generate makes it obvious where to put the key
• If the user's request is genuinely vague or ambiguous along an architecture-changing axis → THEN ask one question

The point is to never block the build on a key the user is going to drop into

.env

Then proceed. Infer everything else from the use case. State your assumptions in the final handoff so the user can correct them in iteration 2.

Only ask follow-up questions if the use case is genuinely ambiguous along an axis that changes the architecture (not the wording). Examples that warrant a follow-up:

• Input is a 200-page document vs. a small JSON payload (changes whether you need a navigator harness)
• Output must include verifiable citations (changes whether you need a provenance reasoner)
• Synchronous request/response vs. event-driven (pattern 8 vs. patterns 1–7)

Examples that do NOT warrant a follow-up: model preference, file naming, port number, code style, what to call the entry reasoner. Decide and state.

The five primitives (cheat sheet — full detail in

choosing-primitives.md

)

• @app.reasoner()

  — every cognitive unit. Schemas come from type hints (no

  input_schema=

  param exists).

• @app.skill()

  — deterministic functions. No LLM. Use whenever an LLM call is overkill.

• app.ai(system, user, schema, model, tools, ...)

  — single OR multi-turn LLM call.

  tools=[...]

  makes it stateful.

  model="..."

  per call overrides AIConfig default.

• app.harness(prompt, provider="claude-code"|"codex"|"gemini"|"opencode")

  — delegates to an external coding-agent CLI. Not a generic tool-using LLM (that's

  app.ai(tools=[...])

  ). REQUIRES the chosen provider's CLI to be installed inside the agent container — see "Harness availability gate" below.

• app.call(target, **kwargs)

  — inter-reasoner traffic THROUGH the control plane. Returns

  dict

  . No model override param — thread

  model

  as a regular reasoner kwarg.

The bias: many small

@app.reasoner()

@app.skill()

app.ai()

app.harness()

Harness availability gate (READ BEFORE USING

app.harness()

)

app.harness()

claude-code

codex

gemini

opencode

python:3.11-slim

app.harness()

The check is automated.

af doctor --json

recommendation.harness_usable

recommendation.harness_providers

Default rule: scaffolds MUST NOT use

app.harness()

recommendation.harness_usable == false

app.ai(tools=[...])

@app.reasoner()

app.ai()

You may use

app.harness()

1. The use case genuinely requires a real coding agent in the loop — i.e. the reasoner needs to write/edit files on disk, run shell commands, or perform complex non-LLM coding work that

   app.ai(tools=[...])

   cannot do.
2. You modify the Dockerfile to install the chosen provider's CLI. Example for Claude Code:

   RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm \
       && npm install -g @anthropic-ai/claude-code \
       && rm -rf /var/lib/apt/lists/*
   

3. You add a startup availability check in

   main.py

   that fails fast with a clear error if the CLI is not on PATH:

   import shutil, sys
   if not shutil.which("claude"):  # or "codex" / "gemini" / "opencode"
       print("ERROR: app.harness(provider='claude-code') requires the `claude` CLI in PATH.", file=sys.stderr)
       sys.exit(1)
   

4. The README explicitly tells the user that the agent container ships with

   claude-code

   (or whatever) and explains the consequence on image size.

If any of the four are not satisfied, do not use

app.harness()

app.ai(tools=[...])

@app.reasoner()

app.harness(provider="claude-code")

claude

When in doubt: don't use harness. The user can ask for it in iteration 2. The first build's job is to work on

docker compose up

Mandatory patterns (every build must have all three)

1. Per-request model propagation

The entry reasoner accepts

model: str | None = None

app.ai(..., model=model)

app.call(..., model=model)

model

curl -X POST http://localhost:8080/api/v1/execute/<slug>.<entry> \
  -d '{"input": {"...": "...", "model": "openrouter/openai/gpt-4o"}}'

If

model

AI_MODEL

app.call()

2. Routers when reasoners > 4

Use

AgentRouter(prefix="domain", tags=["domain"])

app.include_router(router)

prefix="clauses"

clauses_<func_name>

app.call(f"{app.node_id}.clauses_<func_name>", ...)

3. Tags on the entry reasoner

The public entry reasoner is decorated with

tags=["entry"]

Hard rejections — refuse these without negotiation

httpx.post(...)

await app.call(f"{app.node_id}.X", ...)

app.call

asyncio.gather

A → B → C → D

app.ai(prompt=full_50_page_doc)

@app.reasoner

app.ai

app.ai(tools=[...])

while not confident: app.ai(...)

for _ in range(MAX_ROUNDS): ...

app.ai

@app.skill()

curl

docker compose up

node_id

app.call("financial-reviewer.X", ...)

app.call(f"{app.node_id}.X", ...)

AGENT_NODE_ID

model=os.getenv("AI_MODEL", default)

app.ai()

confident

confident: bool

app.harness(provider="claude-code")

claude

app.ai(tools=[...])

input_schema=

output_schema=

@app.reasoner

app.serve()

__main__

app.run()

app.call

dict

list[dict]

Model(**payload)

choosing-primitives.md

choosing-primitives.md

py_compile

docker compose config

status: "succeeded"

result

When the user explicitly demands a rejected pattern, name the rejection, explain why in one sentence, propose the AgentField alternative, and only build it their way after they've confirmed they understand the tradeoff. Add a

# NOTE: User requested X over canonical Y

Mandatory live smoke test before handoff

Static validation —

python3 -m py_compile

docker compose config

A build is not done until the canonical async curl from section 7 of the Output Contract has been fired against the live stack and returned

status: "succeeded"

result

The required sequence before you tell the user "it's ready":

1. docker compose up --build -d

   — bring the stack up.
2. Poll

   /api/v1/discovery/capabilities

   (see section 6) until the agent is registered and every reasoner you defined is listed.
3. Fire the canonical async curl from the README with realistic input.
4. Poll

   /api/v1/executions/<id>

   until

   status

   transitions to either

   succeeded

   or

   failed

   .
5. If

   status == "succeeded"

   : read the

   result

   field and confirm it is a real structured response from your entry reasoner — not an empty object, not a fallback, not a half-finished dict.
6. If

   status == "failed"

   : read the

   error

   field AND tail the agent container logs (

   docker compose logs <slug> --tail=100

   ) to find the actual stack trace. Fix the bug. Go back to step 1.

Do not hand off a build that has only passed static checks. Static validation means "the files are syntactically valid and the compose graph is shaped correctly". It does not mean "the reasoners can actually call each other, the type contracts line up at runtime, the prompts fit in the context window, and the final synthesis produces something coherent." Only the live execution proves those things.

Common runtime failures that ONLY show up in the live smoke test:

• AttributeError: '<object>' has no attribute '<X>'

  — typically a cross-boundary data reconstitution bug (a structured payload arrived as a dict, code tried to access it as a model). See

  choosing-primitives.md

  → "Cross-boundary data does NOT auto-reconstitute".

• AttributeError: '<framework object>' has no attribute '<X>'

  — a framework surface contract was narrower than assumed. The attribute does not proxy. See

  choosing-primitives.md

  → router surface table.

• TypeError: argument after ** must be a mapping, not <T>

  — a downstream reasoner tried to

  **payload

  a value that wasn't a dict. Almost always the same cross-boundary issue.
• A reasoner returned an empty or half-filled schema — usually means an upstream

  .ai()

  call had a

  confident=False

  result and the fallback path returned a safe-default instance, but the orchestrator didn't notice and passed the default downstream as if it were real data.
• The pipeline timed out — either the model is too slow, the fan-out is too wide for the sync endpoint, or a sub-reasoner is stuck waiting on something. Switch the smoke test to async if you haven't already.

The general rule (applies to any multi-component system, not just this one): the only test that proves a distributed system works is the test that exercises the distribution. Running the canonical path against the live system is not optional; it is the single most important validation step, and the one most likely to catch subtle cross-component contract bugs. Never hand off without it.

Rationalization counters & red flags

These thoughts mean STOP. If you notice any of them, re-read the linked reference and reconsider.

analyze()

choosing-primitives.md

verification.md

app.harness()

app.harness()

app.ai(tools=[...])

app.harness(provider='claude-code')

claude

input_schema=

app.ai(tools=[...])

choosing-primitives.md

for

architecture-patterns.md

python3 -m py_compile

docker compose config

scaffold-recipe.md

import requests

app.call(f"{app.node_id}.X", ...)

choosing-primitives.md

app.serve()

app.run()

Output contract (every build)

The final message to the user MUST contain these sections, in this order, in a clean copy-pasteable format. The whole point is the first-time user can read the message top to bottom and within 60 seconds have the system running and a working curl in another terminal.

1. What was scaffolded

Generated file tree with absolute paths.

2. Architecture sketch

4–6 bullets: what each reasoner does, who calls whom, where the dynamic routing happens, where the safety guardrails fire.

3. Assumptions made

5–10 bullets — the things you inferred without asking.

4. 🚀 Run it (3 commands)

cd <absolute_project_path>
cp .env.example .env       # then paste your OPENROUTER_API_KEY into .env
docker compose up --build

Wait until you see

agent registered

5. 🌐 Open the UI

After the stack is up, open these URLs in your browser:

6. ✅ Verify the build (in another terminal)

Use

/api/v1/discovery/capabilities

/api/v1/nodes

# 1. Control plane up?
curl -fsS http://localhost:8080/api/v1/health | jq '.status'

# 2. Agent registered and reasoners discoverable? (PRIMARY CHECK — always use this)
#    Response shape: .capabilities[].reasoners[].id (NOT .reasoners[].name)
curl -fsS http://localhost:8080/api/v1/discovery/capabilities \
  | jq '.capabilities[] | select(.agent_id=="<slug>") | {
      agent_id,
      n_reasoners: (.reasoners | length),
      entry: [.reasoners[] | select(.tags[]? == "entry") | .id],
      all_reasoner_ids: [.reasoners[].id]
    }'

If the JSON above returns your

agent_id

n_reasoners > 0

entry

/api/v1/nodes

health: "unknown"

7. 🎯 Try it — sample async curl (canonical)

Use async. Multi-reasoner compositions routinely exceed the 90-second timeout on the sync endpoint. The canonical smoke test kicks off the async endpoint and polls until the execution succeeds.

# 1. Kick off — returns an execution_id immediately
EXEC_ID=$(curl -sS -X POST http://localhost:8080/api/v1/execute/async/<slug>.<entry_reasoner> \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "<param1>": "<realistic value>",
      "<param2>": <realistic value>,
      "model": "openrouter/google/gemini-2.5-flash"
    }
  }' | jq -r '.execution_id')
echo "Execution: $EXEC_ID"

# 2. Poll until done and print the result
while :; do
  R=$(curl -sS http://localhost:8080/api/v1/executions/$EXEC_ID)
  S=$(echo "$R" | jq -r '.status')
  case "$S" in
    succeeded) echo "$R" | jq '.result'; break ;;
    failed)    echo "$R" | jq '.'; break ;;
    *)         sleep 2 ;;
  esac
done

The payload must use realistic data the user can run as-is and see a real reasoned answer. Do not use placeholder values like

"foo"

"test"

"model"

If the user provided test data in the brief (sample input, sample record, sample document), use THAT data verbatim in this curl. The first execution they run should be the most demonstrative one.

When it is safe to use the sync endpoint instead: only if you can genuinely guarantee the entire pipeline — every layer of fan-out, every child

app.call

.ai()

8. 🏆 Showpiece — verifiable workflow chain

LAST_EXEC=$(curl -s http://localhost:8080/api/v1/executions | jq -r '.[0].workflow_id')
curl -s http://localhost:8080/api/v1/did/workflow/$LAST_EXEC/vc-chain | jq

This is the cryptographic verifiable credential chain — every reasoner that ran, with provenance. No other agent framework gives you this. Mention it.

9. Next iteration upgrade

One concrete suggestion tailored to the shape you actually built. Examples: "swap the intake

.ai()

app.memory

query_planner

query_decomposer

constraint_extractor

TypeScript

A TypeScript SDK exists at

sdk/typescript/

sdk/typescript/

new Agent({nodeId, agentFieldUrl, aiConfig})

agent.reasoner('name', async (ctx) => {...})

Bottom line

Your output is judged by three things:

1. Does the curl return a real reasoned answer? (the user can run the command and see intelligence happen)
2. Does the architecture look like composite intelligence? (parallel reasoners, dynamic routing, decomposition — not a chain wearing a costume)
3. Can a future coding agent extend it without breaking the contract? (CLAUDE.md present, anti-patterns listed, validation commands documented)

If all three are true, you've done it right. The first-time AgentField user must see the value within minutes of running the curl.