Agentfield's architecture is designed around a simple principle: separate the boring infrastructure from the intelligent code.

The control plane handles orchestration, state management, identity, and observability—the infrastructure concerns that every production system needs. Agent nodes contain your business logic and AI—the code that makes decisions and takes actions.

This separation enables what monolithic frameworks can't: independent deployment, automatic coordination, and production-grade reliability.

Autonomous Software Systems Design

Your existing software stack—clients, APIs, services, databases, and external integrations—connects to Agentfield's AI Backend through reasoning and action. The AI Backend handles the infrastructure layer (orchestration, identity, observability, async patterns, memory) while Agent Nodes execute your business logic: research, analysis, customer response, and more.

The Two-Layer Design

from agentfield import Agent

app = Agent("customer-support")

@app.reasoner()
async def triage_ticket(ticket: dict) -> Decision:
    # Your AI logic here
    decision = await app.ai(...)

    # Call other agents if needed
    sentiment = await app.call("sentiment-agent.analyze", ...)

    # Update shared memory
    await app.memory.set("ticket_status", "triaged")

    return decision

How a Request Flows

Agentfield supports two execution modes designed for different use cases. Understanding both reveals how the architecture enables scalability, observability, and event-driven patterns.

Why agent coordination through the control plane matters: Notice how Agent1 calls Agent2 via app.call(), which routes through the control plane—not direct HTTP between agents. This architectural choice enables scalability patterns that direct agent-to-agent communication can't achieve: automatic load balancing across agent instances, complete observability of the execution DAG, circuit breaking when agents fail, and context propagation without manual correlation IDs. The control plane isn't just separating infrastructure from logic—it's the coordination hub that makes distributed agent systems production-ready.

Synchronous Execution (Fast Response)

For real-time workflows where you need immediate results:

POST /api/v1/execute/support-agent.triage_ticket
{
  "input": {"ticket_id": 12345, "message": "I can't log in"}
}

# Returns immediately with result (typical: 500ms - 30s)
Response: 200 OK
{
  "execution_id": "exec_abc123",
  "status": "completed",
  "result": {"priority": "high", "escalate": true},
  "duration_ms": 1247
}

What happens:

1. Control plane generates execution_id, persists to database before execution
2. Routes request to agent node with context headers (X-Run-ID, X-Execution-ID, X-Session-ID)
3. Agent executes your Python code with automatic context
4. Control plane updates database with result, returns to client

Perfect for: User-facing APIs, chat interfaces, interactive workflows

Asynchronous Execution (Scalable Processing)

For long-running tasks, batch processing, or event-driven architectures:

POST /api/v1/execute/async/analytics-agent.process_dataset
{
  "input": {"dataset_id": "large_dataset"},
  "webhook": {
    "url": "https://your-app.com/webhooks/analytics",
    "secret": "your_webhook_secret"
  }
}

# Returns immediately (< 50ms)
Response: 202 Accepted
{
  "execution_id": "exec_xyz789",
  "status": "queued",
  "webhook_registered": true
}

What happens:

1. Control plane persists execution with status queued
2. Returns immediately to client (HTTP 202 Accepted)
3. Background worker pool picks up the job from queue
4. Agent executes asynchronously (can run for minutes/hours)
5. Webhook fires when complete with signed payload

Perfect for: Data processing, ML inference, scheduled jobs, microservices integration

Learn more: Async Execution & Webhooks →

The Architecture Benefits You Get

What Your Agent Code Sees

Both execution modes deliver the same developer experience:

from agentfield import Agent

app = Agent("support-agent")

@app.reasoner()  # Works in both sync and async mode
async def triage_ticket(ticket: dict) -> Decision:
    # Context automatically available from headers
    # No need to pass execution_id, session_id manually

    # Memory scoped to session (user), actor (team), workflow
    history = await app.memory.get("customer_history")

    # Call other agents - context propagates automatically
    sentiment = await app.call("sentiment-agent.analyze",
                              text=ticket["message"])

    # AI reasoning
    decision = await app.ai(
        system="You're a support triage expert",
        user=f"History: {history}\nSentiment: {sentiment}",
        schema=Decision
    )

    # Observability notes (tied to execution_id automatically)
    app.note(f"Triaged as {decision.priority}")

    return decision

Key insight: You write the same code whether client calls sync or async. The control plane handles execution mode, queuing, webhooks, and DAG construction.

When to Use Each Mode

Production patterns: See Async Execution guide →

What's Tracked Automatically

Every execution (sync or async) captures:

• Timing: Start, end, duration
• Identity: Agent, reasoner, session, actor
• Lineage: Parent-child relationships (execution DAG)
• Payload: Input/output (configurable retention)
• Events: Notes, errors, status transitions
• Webhooks: Delivery status and retries

The control plane manages this infrastructure. You focus on agent logic.

Key Components

Deployment Topologies

# Build the agentfield binary (from control-plane directory)
./build-single-binary.sh

# Run from an agent package directory (requires agentfield.yaml)
agentfield dev            # Run agent in dev mode
agentfield run my-agent   # Your agent node

services:
  af-server:
    image: ghcr.io/agent-field/agentfield-control-plane:v0.1.8
    ports: ["8080:8080"]

  my-agent:
    build: .  # Path to your agent directory (with Dockerfile, main.py, requirements.txt)
    environment:
      - AGENTFIELD_SERVER=http://af-server:8080

app = Agent(
    node_id="my-agent",
    agentfield_server=os.getenv("AGENTFIELD_SERVER", "http://localhost:8080"),
)

# Control Plane Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentfield-control-plane
spec:
  replicas: 3
  # ... horizontal scaling, health checks, etc.

---

# Agent Node Deployment (independent)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: customer-support-agent
spec:
  replicas: 2
  # ... scales independently of other agents

Why This Architecture Matters

The Philosophy

Traditional agent frameworks optimize for single-app development. Agentfield optimizes for distributed production systems.

We chose Go for the control plane because boring infrastructure should be fast, reliable, and cheap to run. We chose Python for agent nodes because that's where AI developers already work.

We separate concerns so teams can own their agents, deploy independently, and share state automatically. We make identity automatic so compliance teams get proofs, not promises.

Deploy to Production

The architecture you just learned about works identically from local development to enterprise Kubernetes:

Next: Building Your First Agent →

Ready to see this in action? The 5-minute quick start shows you exactly how these pieces work together.