repository·main·Indexed 22 days ago
https://github.com/agent-field/agentfieldAgentField is an open-source AI backend and control plane for building and running AI agents as scalable microservices. It provides orchestration, routing, memory, and observability for multi-agent workflows. The documentation covers control plane setup, Decentralized Identity (DID) database schema migrations, Web UI development using React, and installation and release automation scripts.
The SDK is organized into several functional modules:
agent: Used to build AgentField-compatible agents and register reasoners or skills.client: Provides a low-level HTTP client for interacting with the AgentField control plane.types: Contains shared data structures and contracts used across the SDK.ai: Provides helpers for interacting with AI providers via the control plane.AgentField Desktop is a companion application designed to manage your local AgentField environment. It provides a centralized UI to monitor the health of your local control plane, manage agent nodes on your machine, and view live execution activity. It also allows for one-click installation of curated agents.
Key features include:
running, stopped, or unknown) of installed agents.AgentField provides example agents across Python, TypeScript, and Go to demonstrate various capabilities. Use this table to find the right starting point for your use case.
| Use Case | Python | TypeScript | Go |
|---|---|---|---|
| Getting Started | hello_world | init-example | go_agent_hello_world |
| Basic RAG | hello_world_rag | discovery-memory | - |
| Production RAG | agentic_rag | - | - |
| Documentation Q&A | documentation_chatbot | - | - |
| RAG Evaluation | rag_evaluation | - | - |
| Deep Research | deep_research_agent | - | - |
| Image Generation | image_generation_hello_world | - | - |
| Multi-Agent Simulation | simulation_engine | simulation | - |
| Serverless Deployment | serverless_hello | serverless-hello | - |
| Verifiable Credentials | - | verifiable-credentials | - |
The Python SDK (sdk/python) acts as a thin client for the control plane's REST API. It is designed for ease of use with the following features:
pyproject.toml.The Go SDK (sdk/go) is an idiomatic client designed for high-performance agent orchestration. It is ready for consumption via go get and is organized into several key packages:
agent: Core agent logic.client: Client implementation.types: Shared data structures.ai: AI-specific primitives.The Go SDK implements interfaces shared by the control plane, allowing it to integrate deeply with the agent mesh.
When an agent project grows to more than 4 reasoners, you should move them into a reasoners/ package to maintain clean architecture.
<slug>/
├── main.py
└── reasoners/
├── __init__.py
├── models.py # All Pydantic schemas
├── helpers.py # Plain Python utilities
└── <domain>.py # One AgentRouter per logical groupingmodels.py: Contains every Pydantic schema used in the system. This centralizes type-checking and prevents circular imports.helpers.py: Contains plain Python utilities (math, prose rendering, etc.). Do not use decorators here. Use @app.skill() only if the function needs to be discoverable by the control plane for external calls. Internal logic should remain as plain Python to avoid decorator overhead.<domain>.py: Defines an AgentRouter for a specific logical grouping of reasoners.AgentRouterAn AgentRouter allows you to group reasoners. Its methods (ai, call, memory, harness) proxy to the main agent.
Important Gotchas:
router.node_id and other data attributes do not proxy. You must read the node ID from the environment: NODE_ID = os.getenv("AGENT_NODE_ID", "<slug>").prefix argument in AgentRouter(prefix="...") controls namespacing. If prefix="clauses", reasoner IDs become clauses_<func_name>. Use prefix="" to keep them raw.Example Router Implementation:
import os
from agentfield import AgentRouter
from .models import MyResult
NODE_ID = os.getenv("AGENT_NODE_ID", "<slug>")
router = AgentRouter(prefix="", tags=["domain_name"])
@router.reasoner()
async def my_reasoner(payload: dict, model: str | None = None) -> MyResult:
return await router.ai(system="...", user=str(payload), schema=MyResult, model=model)Registering a Router in main.py:
from reasoners import domain_router
# ... inside app setup
app.include_router(domain_router)import os
from agentfield import AgentRouter
from .models import MyResult
NODE_ID = os.getenv("AGENT_NODE_ID", "<slug>")
router = AgentRouter(prefix="", tags=["domain_name"])
@router.reasoner()
async def my_reasoner(payload: dict, model: str | None = None) -> MyResult:
return await router.ai(system="...", user=str(payload), schema=MyResult, model=model)The Control Plane dispatches triggers using a specific envelope format. The SDKs automatically unwrap the event object, build the TriggerContext from the _meta field, and apply any configured transform function before delivering the payload to your handler.
If a call is made directly (without the _meta envelope), the payload is passed through unchanged.
{
"event": { /* raw provider payload */ },
"_meta": {
"trigger_id": "tr_abc",
"source": "stripe",
"event_type": "payment_intent.succeeded",
"event_id": "evt_123",
"idempotency_key": "evt_xxx",
"received_at": "2026-04-28T22:29:54Z",
"vc_id": "vc_456"
}
}When using app.call(), you are crossing a serialization boundary.
Crucial Gotcha: Even if you pass a Pydantic model into app.call(), the receiver will receive a plain dict. You must either:
Model(**payload).Data Formats:
if result.type == "X").AgentField is a control plane that turns plain Python, Go, or TypeScript functions into production-ready microservices.
Key orchestration features include:
app.call(), an agent can call itself or other agents. This allows a single request to trigger a distributed tree of sub-tasks (fan-out) managed by the control plane.app.ai(), you can request LLM responses that conform to a specific schema (e.g., a Pydantic model), ensuring typed AI judgment.app.pause() method allows an agent to suspend execution, wait for human approval via a webhook, and resume once approved.app.run() automatically exposes your decorated functions as REST endpoints.When designing an agent orchestration, do not decompose by data flow (e.g., fetch → parse → analyze). Instead, decompose by cognitive jobs—the mental moves an expert makes. This produces smaller, more verifiable, and more independent reasoning slots.
To perform cognitive decomposition, ask:
Example (Invoice Intake):
.ai() slot).The Snowflake node enforces several security and operational guardrails to protect data and manage resources:
query_readonly, DDL, DML, file transfers, role changes, and stored procedure calls are explicitly denied.NEEDS_REVIEW if prompts or semantic context are insufficient for a safe execution.