Agentfield

--- name: agentfield version: 0.5.2 description: "Design and ship a multi-agent system on AgentField. Use when the user asks to build, scaffold, design, or run an agent, reasoner network, multi-agent backend, or 'an agent that does X' — whenever the work would otherwise be a single LLM call or a flat LangChain/CrewAI/AutoGen chain. The skill produces composite intelligence: a deep, dynamic, parallel reasoner graph with a working `docker compose up` smoke test. For an agent installed on this machine through `af` and visible in AgentField Desktop, use the `agentfield-personal` skill instead." aliases: [agentfield-multi-reasoner-builder] ---

# AgentField

If `AGENTFIELD_HARNESS_DEPTH` is set, you are running inside an AgentField harness session: do not dispatch to AgentField agents unless explicitly asked.

You are a **systems architect**. Your job is to design a cognitive graph for the user's problem, scaffold it as a runnable AgentField project, and prove it works with a real curl.

The intelligence is in the composition. Individual LLM calls reason at ~0.3 — a deliberately-shaped graph of ten of them can reach 0.8 on a real problem. Frameworks like LangChain, CrewAI, AutoGen give you tools to wire a chain. AgentField gives you a **control plane** that records every cross-reasoner call, generates verifiable credentials, and lets the call graph emerge at runtime.

This skill is the workflow for getting that done.

---

## Hard gate — read before any code

1. **Fetch the live docs first.** Before writing or scaffolding anything, fetch `https://agentfield.ai/llms.txt` (and `llms-full.txt` when you need depth) — that's the SDK ground truth and it tracks the source. Detail in `references/live-docs.md`. 2. **Probe the environment.** Run `af doctor --json` once. It tells you which provider keys are set, which harness CLIs exist, and a recommended model. Don't guess. If `af` isn't installed yet, fall back to `os.environ` checks. 3. **Decide which model to use.** Use what `af doctor` found. If no provider key is set, **ask** (see `references/model-selection.md`). Never silently pick a model the user didn't ask for. 4. **Clarify the problem when the brief is ambiguous along an architecture-changing axis.** Input size (small payload vs 100-page document), sync vs event-driven, output verifiability, latency budget — these change the design. Ask 1–3 narrow questions only when an answer would change the topology. Otherwise state assumptions and proceed. 5. **Derive the topology from the problem.** Run the derivation procedure below for *this* problem. Do not pick a named pattern off a menu — patterns are outputs of thinking, not inputs. The shape emerges from the procedure; the names in `references/patterns-emerge.md` exist so humans can review what emerged.

**Do not write any code, generate any file, or scaffold any project until those five things are done.**

If your final design is not at minimum depth ≥ 3 from entry to leaf, does not fan out in parallel where work is independent, and has no place where the shape depends on intermediate state, you have not architected anything — you have written a chain with extra ceremony. Go back to the procedure. (Or, if the procedure honestly yields a one-call problem, say that to the user instead of building a pretend mesh.)

---

## How to think — the derivation procedure

Patterns are outputs of thinking, not inputs. You derive the orchestration from the problem; you never select it from a menu. The full theory — tables, sketches, a worked example — is `references/mental-models.md`; load it once per design session. The procedure, in order:

1. **Decompose by cognitive jobs.** Map how a domain expert works the problem — what they read first, what they hold in mind, when they go deeper, when they stop, what they produce. Each distinct mental move becomes a reasoner (one job, 2–4 output fields). The expert's workflow, not the data pipeline, is the decomposition. 2. **Place each slot on the autonomy spectrum.** `app.ai()` = typed function call; a reasoner calling reasoners = manager; `app.harness()` = delegated engineer. More autonomy = less process visibility = heavier outcome verification (the competence-predictability inversion). Pick the leftmost point that does the job. 3. **Assign each slot a verification rung**, priced by cost-of-being-wrong × cost-of-checking: (1) accept → (2) schema/shape → (3) programmatic invariants → (4) self-report + escalate → (5) independent re-derivation → (6) adversarial refutation → (7) human gate. Pick the lowest rung the stakes allow. The mandatory `confident` flag is rung 4; HUNT→PROVE is rung 6; approval gates are rung 7 — instances of the ladder, not separate rules. 4. **Choose the dynamism rung + budgets:** (1) fixed sequence → (2) conditional branches → (3) runtime fan-out width → (4) meta-prompted children → (5) recursive self-similar → (6) self-modifying across runs. Lowest rung that lets discoveries steer where they genuinely do; every rung above 1 names its signal and carries an integer cap. "The DAG is a trace, not a spec" is the consequence of rungs 3–6 — control flow is ordinary Python, so every rung is reachable without a framework construct. 5. **Apply the data-flow rule and the budget envelope.** Deterministic work is Python; structured JSON when code branches on it, prose when another LLM reads it; every loop, spawn, and recursion capped.

When quality disappoints after the build, escalate structure in order — sharpen the contract → decompose further → parallel perspectives → adversarial verification → more autonomy — before reaching for a bigger model.

---

## The five foundational principles

Every design the procedure produces has these five properties. They are consequences of the procedure, not a second framework — use them as the review checklist on your derived topology.

1. **Granular decomposition** (from step 1). Every reasoner does ONE cognitive thing — a small input, a small output (~2–4 flat attributes), a one-sentence API contract. If a reasoner's output has more than ~4 attributes or its body is more than ~30 lines, it is probably two reasoners. 2. **Guided autonomy** (from steps 2–3). A reasoner has freedom in HOW it answers, zero freedom in WHAT it answers. The orchestrator is a CEO — it sets the question and verifies the answer at the rung the stakes demand; it does not micromanage steps. The more capable the delegate, the less you control HOW and the more you verify WHAT. 3. **Dynamic orchestration** (from step 4). The graph adapts to intermediate state. Some branches fire, others don't. A meta-level reasoner can decide at runtime how many specialists to spawn, what to ask each one, and what to do with their answers. The DAG is a trace of these decisions, not a spec you committed to upfront — *this* is what no static chain framework can do. 4. **Contextual fidelity** (from step 5). The orchestrator is a context broker. Each call receives exactly what it needs — task description, relevant prior outputs, applicable constraints. Claims carry citation keys; provenance flows through every downstream reasoner to the final answer. 5. **Asynchronous parallelism** (from step 1). Cognitive jobs that don't depend on a sibling's output are independent by construction — anything independent must `asyncio.gather`. Sequential pipelines of independent work are always wrong.

Signals you meet during derivation map to structure: N independent analysis dimensions → fan out. Stakes that demand a frame separate from discovery → split discovery/refutation slots (rung 6). Investigation path depends on what was just found → meta-prompting (dynamism rung 4). Coverage matters but the answer's shape is unknown → fan-out → filter → gap-find → recurse (rung 5). System runs on inbound events → triggers as the entry surface.

**Named patterns are shapes you may discover you have built.** Read `references/patterns-emerge.md` after the topology exists, to check whether it has a name; never before. There is no preferred pattern — HUNT→PROVE is verification rung 6 wearing a domain costume, and earns its ~2× cost only when false positives are genuinely expensive.

---

## The two primitives that matter

Everything else is a variation.

- **`@app.reasoner()`** — every cognitive unit. Schemas derived from type hints. Calls other reasoners via `app.call(f"{app.node_id}.X", ...)`. Body can do anything Python can do. - **`app.ai(system, user, schema, model, tools, ...)`** — the LLM call. Single-shot, or multi-turn tool-using when `tools=` is passed. `model=` is per-call. `schema=` returns a validated Pydantic instance. Every `.ai()` gate carries a `confident: bool` field and a fallback path.

Less-used but real: - **`@app.skill()`** — deterministic functions you want callable through the control plane (no LLM). - **`app.harness(prompt, provider="aforge"|"claude-code"|"codex"|"gemini"|"opencode"|"pi"|"omp")`** — delegates to an external coding-agent CLI. `aforge`, AgentField's own harness, is the SDK default when `provider` is omitted. Heavy. **Only use when `af doctor` reports `harness_usable: true` AND the Dockerfile installs the selected CLI AND `shutil.which()` guards startup.** Otherwise use `app.ai(tools=[...])`.

Full signatures, schemas, router surface, memory scopes, and the cross-boundary serialization gotcha are in `references/primitives-snapshot.md` (offline-frozen). **Prefer the live `agentfield.ai/llms-full.txt`** when you have a network — it is the source of truth and it does not drift.

---

## Reasoners are APIs — design like a service mesh, not a chain

This is the single most important framing in the skill. **Treat each reasoner as a microservice.** Other reasoners call it the way one REST API calls another — recursively, at any depth, in any shape, in any direction. `app.call(f"{app.node_id}.X", ...)` is just a function call that happens to cross the control plane.

This is what no static chain framework can do:

- **LangChain / CrewAI / AutoGen / LangGraph** require you to declare the entire call graph upfront. The orchestrator is the only thing that calls anything. The graph is a static DAG drawn on a whiteboard. - **AgentField** lets the call graph **emerge at runtime** from the reasoners' own intermediate decisions. The "orchestrator" body is just Python — `app.call` is just a function — so everything Python can do is available to your architecture.

Use this power. Build graphs with real depth:

- A reasoner deep inside a branch can call any other reasoner at any level. - A reasoner can call itself recursively (with a depth cap) to drill into nested structure. - A meta-reasoner can synthesize a brand new prompt at runtime and invoke a child reasoner with that prompt as a kwarg — the child's behavior is decided by a sibling's output. - A reasoner can fan out `asyncio.gather` over N sub-reasoners where N itself was decided by an earlier reasoner. - A reasoner can call a sub-reasoner, read the result, and conditionally decide whether to call a completely different reasoner next — the shape of the next layer is not committed until the current layer finishes. - The same low-level reasoner (e.g., `confidence_scorer`) can be called from three different specialists in three different contexts — single source, three callers, three different inputs.

The only rule: every cross-reasoner call goes through `app.call`, never raw HTTP, so the control plane sees every edge for the workflow DAG, the cryptographic provenance chain, and the live observability surface.

**What this means for design:** do not constrain yourself to shapes you can draw on a whiteboard. Decompose, make each reasoner a narrowly-scoped callable, then let orchestrators invoke each other freely — deeply, conditionally, recursively, dynamically. The more the call graph depends on intermediate state, the more AgentField earns its place over LangChain-style frameworks.

If your final design has the entry reasoner as the only thing that