The Problem

Teams building AI agents need backend infrastructure that treats agents as callable services rather than chatbot workflows. The repository provides the control plane and SDKs to make agents observable, auditable, and identity-aware from day one, but the codebase carries significant technical debt that affects onboarding and safety.

What This Does

AgentField consists of four projects: control-plane (1005 files, 922 code files) provides the HTTP API, routing, and coordination; sdk (413 files, 391 code files) offers Python, Go, and TypeScript kits; examples (213 files) contain benchmark and demo workloads; and scripts (19 files) handle tooling. The control-plane exposes REST endpoints for agent execution, execution record management, and configuration—every function becomes a REST endpoint, every agent gets a cryptographic identity.

Key files: control-plane/internal/server/server.go orchestrates routing; control-plane/internal/handlers/execute.go defines execution handlers called from 6 other files; sdk/typescript/src/agent/Agent.ts is the central TypeScript agent module (1385 lines, 395 branch points, imports/imported by 41 modules). The sdk/python/agentfield/agent.py counterpart is equally oversized.

How It Is Wired

Execution starts at two entry points: control-plane/cmd/af/main.go:32 (main reaches 94 functions, called by nothing else in the repo) and control-plane/internal/cli/commands/run.go:69 (execute reaches 80 functions, called by nothing else). From main, execution flows to RegisterReasoner → handler registration → API route setup. The internal call graph shows Run called from 419 places, New from 356, making these the highest-blast-radius functions.

Traced paths: main → Execute [filesystem via os.WriteFile]; Start → cleanupLoop → performCleanup → RetryStaleWorkflowExecutions [db via workflowStmt.ExecContext]; execute → ListInstalledPackages → loadRegistryDirect [filesystem via os.ReadFile].

The module graph has 24 modules in circular dependencies, with sdk/typescript/src/agent/Agent participating in an import cycle with sdk/typescript/src/types/agent.ts and sdk/typescript/src/client/AgentFieldClient.ts. The hub module control-plane/web/client/src/lib/utils is depended on by 51 other modules—changes here have high-blast-radius impact.

How To Use It

Setup: The repo uses Makefile for build targets; control-plane/go.mod pins Go dependencies; control-plane/web/client/package.json and package-lock.json manage the TypeScript frontend. No single install command is documented across the four projects; the Makefile in the root likely orchestrates them.

Configuration: Environment files exist but carry secrets: control-plane/.env.dev, control-plane/web/client/.env, control-plane/web/client/.env.production are tracked despite .gitignore exclusions. A control-plane/.env.example.tmpl template is present. No pyproject.toml or go.mod at the root implies per-project dependency management.

Running it: To start the server, the entry point is control-plane/cmd/af/main.go or control-plane/cmd/agentfield-server/main.go. The control-plane/docker-compose.dev.yml and control-plane/tools/perf/Dockerfile suggest docker compose -f control-plane/docker-compose.dev.yml up for local development.

Real-World Use

An insurance claims adjuster agent written in Python:

from agentfield import Agent, AIConfig
from pydantic import BaseModel

app = Agent(
    node_id="claims-processor",
    version="2.1.0",
    ai_config=AIConfig(model="anthropic/claude-sonnet-4-20250514"),
)

class Decision(BaseModel):
    action: str  # "approve", "deny", "escalate"
    confidence: float
    reasoning: str

@app.reasoner(tags=["insurance", "critical"])
async def evaluate_claim(claim: dict) -> dict:
    decision = await app.ai(
        system="Insurance claims adjuster. Evaluate and decide.",
        user=f"Claim #{claim['id']}: ...",
    )
    return decision.model_dump()

This registers a reasoner tagged for A/B testing and blue-green deploys. The evaluate_claim function becomes a REST endpoint via the control-plane routing layer. Execution records are stored in a database through control-plane/internal/server/knowledgebase/kb.go methods (Topics, Add, AddBatch).

Code Health & Issues

Static analysis of 1479 files found 350 issues across 6 kinds:

  • [HIGH/cognitive_load] Oversized files: sdk/typescript/src/agent/Agent.ts, sdk/python/agentfield/agent.py, sdk/python/agentfield/client.py (1385 lines each, hard to hold in one head)
  • [HIGH/soundness] Import cycle member: sdk/typescript/src/agent/Agent.ts participates in a circular import with types and client modules
  • [HIGH/cognitive_load] Deep nesting: max indentation depth 12 in sdk/python/agentfield/agent.py and control-plane/web/client/src/components/workflow/TimelineNodeCard.tsx
  • [HIGH/clarity] Hub module: control-plane/web/client/src/lib/utils depended on by 51 modules; control-plane/web/client/src/components/ui/button depended on by 51 modules
  • [MEDIUM/cognitive_load] High branching density: 395 branch points over 1385 lines in sdk/typescript/src/agent/Agent.ts and sdk/typescript/src/memory/MemoryClient.ts
  • [MEDIUM/resilience] Broad exception handling: bare except in sdk/python/agentfield/logger.py, sdk/python/agentfield/types.py, sdk/python/agentfield/agent.py

Code Health Audit (13 findings):

  • [CRITICAL] Upgrade golang.org/x/crypto@0.49.0 carrying CVE-2026-42508 (critical) — vulnerable code installs as-pinned
  • [HIGH] Untrack control-plane/web/client/.env though .gitignore excludes it — credentials in use are the ones actually loaded
  • [HIGH] Pin GitHub Actions to commit SHAs: docker/setup-buildx-action@v3, docker/build-push-action@v5, etc. Tags can move, running with whatever owner last pushed
  • [HIGH] control-plane/.env.dev committed with live credentials — the most common route for keys to reach public clones
  • [HIGH] control-plane/.env.dev tracked although .gitignore says to ignore — author already decided this file must never commit
  • [MEDIUM] python:3.11-slim base image in control-plane/tools/perf/Dockerfile not pinned by digest — mutable base means different CVE sets per build
  • [MEDIUM] No Dependabot/Renovate configured across 7 manifests

The Bottom Line

This is a functional agent control plane with good architectural intent—treating agents as APIs with cryptographic identities, audit trails, and routing infrastructure. The SDKs cover Python, Go, and TypeScript, and the examples provide concrete starting points. However, the codebase has serious maintainability and security debt: three oversized modules spanning 1385 lines each, an active import cycle, committed .env files with live credentials, and a critical Go crypto vulnerability in the pinned dependency. Teams needing to ship production agent infrastructure should plan to refactor the agent modules and rotate all committed secrets before deploying. The control-plane project is the most substantial component; the SDKs and examples are valuable but inherit the same structural issues.