agentfield

# AgentField

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. **Design the topology from the problem.** Walk the five principles below for *this* problem. Do not pick a named pattern off a menu. The shape emerges; the pattern names are vocabulary to describe 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 principles.

---

## The five foundational principles

Apply each one to the user's specific problem. The topology falls out of the answers.

1. **Granular decomposition.** 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.** 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; it does not micromanage steps.
3. **Dynamic orchestration.** 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. *This* is what no static chain framework can do.
4. **Contextual fidelity.** 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.** Decompose to parallelize. Anything that doesn't depend on a sibling's output must `asyncio.gather`. Sequential pipelines of independent work are always wrong.

Ask the question under each principle when you design. Where decomposition produces N independent dimensions → fan out. Where verification needs a frame separate from discovery → split discovery/proof reasoners. Where the investigation path depends on what was just found → meta-prompting / dynamic dispatch. Where coverage matters but the answer's shape is unknown → fan-out → filter → gap-find → recurse. Where the system runs on inbound events → triggers as the entry surface.

**Named patterns are emergent consequences, not templates.** Read `references/patterns-emerge.md` after you have a shape, to give the shape a name; not before. There is no preferred pattern — HUNT→PROVE is one option of many and earns its 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="claude-code"|"codex"|"gemini"|"opencode")`** — delegates to an external coding-agent CLI. Heavy. **Only use when `af doctor` reports `harness_usable: true` AND the Dockerfile installs the 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