# AgentField

> An open-source control plane that makes agents callable like any other API — plain Python, Go or TypeScript functions in, REST endpoints, distributed fan-out and signed audit trails out

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: Go
- Licence: Apache-2.0
- Repository: https://github.com/Agent-Field/agentfield
- Website: https://agentfield.ai
- Canonical page: https://ai-tldr.dev/tools/agentfield/

## In short

AgentField is an open-source control plane for running agents as ordinary backend services. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in Go and licensed Apache-2.0. To get started: install the CLI and control plane.

## Overview

AgentField is an open-source control plane for running agents as ordinary backend services. You write the agent logic as plain functions — no DSL, no YAML, no graph wiring — and the project turns each one into a REST endpoint that anything in your stack can call: a frontend, another backend, a cron job, or another agent. `app.run()` is the whole deployment story; a reasoner named `research` on a node named `researcher` becomes `POST /api/v1/execute/researcher.research`. SDKs exist for Python, Go and TypeScript, and there is a REST API for everything else.

What you get beyond the endpoint is the part that is tedious to build yourself. `app.ai()` calls a model and returns structured output against a Pydantic schema. `app.call()` routes to another agent — or back into the same one — through the control plane, which is what turns a recursive function into distributed fan-out: the README's research example breaks a question into sub-questions and `asyncio.gather`s the branches, and the control plane handles the queueing, the retries and the trace for every branch. `app.pause()` suspends an execution for human approval, notifies a webhook, and resumes when someone signs off, with an expiry on the request.

The control plane itself is a stateless Go service. Agents register their capabilities from wherever they run — a laptop, Docker, Kubernetes — and the plane routes calls between them, records each execution as a DAG, and enforces policy. Governance is built in rather than bolted on: every agent gets a W3C DID instead of a shared API key, each execution produces a verifiable credential you can check offline with `af vc verify audit.json`, and tag-based policy gates ("only agents tagged finance can call this") are enforced by the infrastructure rather than by a prompt.

There is also a prompt-to-production path. The installer drops the `aforge` coding harness alongside the `af` CLI, and an `/agentfield` command in Claude Code, Codex, Gemini CLI, OpenCode, Aider, Windsurf or Cursor takes a one-line spec and scaffolds a Docker Compose stack — the agent, the control plane and a REST endpoint you can `curl` immediately. Newer releases add Harness Orchestration for multi-turn coding agents on top of the same plane.

## What it does

- Plain functions become REST endpoints — `app.run()` exposes every reasoner at `/api/v1/execute/<node>.<function>`, with Python, Go and TypeScript SDKs
- Distributed fan-out: `app.call()` routes through the control plane, so recursion across thousands of branches gets queues, backpressure, auto-retries and a DAG trace without a broker to set up
- Structured LLM output via `app.ai()` against a declared schema, with per-agent model configuration and versioned nodes for canary, A/B and blue-green rollouts
- Human-in-the-loop with `app.pause()` — execution suspends, a webhook fires, and the run resumes on approval or expires after a set window
- Cryptographic identity and audit: a W3C DID per agent, verifiable credentials per execution (`af vc verify`), and tag-based policy gates enforced by the control plane
- A dashboard for workflow DAGs, execution traces, agent-fleet health and audit trails, plus `af service status` and a macOS menu-bar control for the local plane

## Getting started

The installer puts the `af` CLI and the `aforge` coding harness in ~/.agentfield/bin. On macOS it also registers the control plane to start at login under launchd and adds a menu-bar icon — stop it with `af service stop` rather than `kill`, which looks like a crash and triggers a restart. Pass `--no-tray` to skip the menu-bar integration or `--no-aforge` to skip the harness.

1. Install the CLI and control plane

```bash
curl -fsSL https://agentfield.ai/install.sh | bash
```

2. Scaffold an agent and start the plane

   Run the server in one terminal and the agent in another; the agent auto-registers its capabilities with the control plane on startup, and the dashboard comes up on port 8080.

```bash
af init my-agent --defaults
cd my-agent && pip install -r requirements.txt
af server          # Terminal 1 → Dashboard at http://localhost:8080
python main.py     # Terminal 2 → Agent auto-registers
```

3. Call it like any other service

   Every reasoner is reachable at /api/v1/execute/<node_id>.<function>. Nothing about the call is AgentField-specific — it is a POST with a JSON body.

```bash
curl -X POST http://localhost:8080/api/v1/execute/my-agent.demo_echo \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Hello!"}}'
```

4. Write the agent as ordinary functions

   `app.ai()` returns structured output against the schema you declare, and `app.call()` routes back through the control plane — which is what turns this recursion into bounded, traced, distributed fan-out.

```python
import asyncio
from agentfield import Agent, AIConfig
from pydantic import BaseModel

app = Agent(
    node_id="researcher",
    version="1.0.0",
    ai_config=AIConfig(model="anthropic/claude-sonnet-4-20250514"),
)

class SubQuestions(BaseModel):
    questions: list[str]

@app.reasoner(tags=["research"])
async def research(question: str, depth: int = 0, model: str | None = None) -> dict:
    if depth >= 3:  # depth cap keeps fan-out bounded
        answer = await app.ai(system="Answer directly and concisely.", user=question, model=model)
        return {"question": question, "answer": answer}

    plan = await app.ai(
        system="Break this into 3-5 independent sub-questions.",
        user=question, schema=SubQuestions, model=model,
    )

    branches = await asyncio.gather(*[
        app.call(f"{app.node_id}.research", question=q, depth=depth + 1, model=model)
        for q in plan.questions
    ])

    synthesis = await app.ai(system="Synthesize these findings.", user=str(branches), model=model)
    return {"question": question, "answer": synthesis, "branches": branches}

app.run()
```

5. Or describe the system and let a coding agent build it

   The `/agentfield` command works in Claude Code, Codex, Gemini CLI, OpenCode, Aider, Windsurf and Cursor. It returns a Docker Compose stack wired end to end — agent, control plane and a REST endpoint ready to curl.

```text
/agentfield Build a claims processor with risk scoring, pattern detection,
and human approval for low-confidence decisions.
```

## When to use it

- Reach for it when an agent needs to be callable by the rest of your stack — a frontend, a cron job, another service — rather than living inside one chat loop
- Reach for it when a single request has to fan out across hundreds or thousands of sub-tasks and you do not want to stand up a broker, a queue and a retry policy first
- Reach for it when a workflow needs a human to approve low-confidence decisions mid-execution without losing the run
- Reach for it when compliance wants per-agent identity, an offline-verifiable receipt for every execution, and policy enforced by infrastructure instead of by prompt wording
