README
¶
AgentField Control Plane
The AgentField control plane orchestrates agent workflows, manages verifiable credentials, serves the admin UI, and exposes REST/gRPC APIs consumed by the SDKs.
Requirements
- Go 1.23+
- Node.js 20+ (for the web UI under
web/client) - PostgreSQL 15+
Quick Start
# From the repository root
cd control-plane
go mod download
cd web/client
npm install
npm run build
cd ../..
# Run database migrations (requires AGENTFIELD_DATABASE_URL)
goose -dir ./migrations postgres "$AGENTFIELD_DATABASE_URL" up
# Start the control plane
AGENTFIELD_DATABASE_URL=postgres://agentfield:agentfield@localhost:5432/agentfield?sslmode=disable \
go run ./cmd/server
Visit http://localhost:8080/ui/ to access the embedded admin UI.
Local Development with Hot-Reload
For development with hot-reload, use the dev.sh script. This automatically rebuilds and restarts the server when Go files change.
cd control-plane
./dev.sh # SQLite mode (default, no dependencies)
./dev.sh postgres # PostgreSQL mode (set AGENTFIELD_DATABASE_URL first)
The server runs at http://localhost:8080 and will automatically reload when you modify .go, .yaml, or .yml files.
Notes:
- Uses Air for hot-reload (auto-installed if missing)
- Web UI is not included in dev mode; run
npm run devseparately inweb/client/if needed
Configuration
Environment variables override config/agentfield.yaml. Common options:
AGENTFIELD_DATABASE_URL– PostgreSQL DSNAGENTFIELD_HTTP_ADDR– HTTP listen address (0.0.0.0:8080by default)AGENTFIELD_LOG_LEVEL– log verbosity (info,debug, etc.)
Sample config files live in config/.
Web UI Development
cd control-plane/web/client
npm install
npm run dev
# Build production assets embedded in Go binaries
cd ../..
npm run build
Run the Go server alongside the UI so API calls resolve locally. During production builds the UI is embedded via Go's embed package.
Database Migrations
Migrations use Goose:
AGENTFIELD_DATABASE_URL=postgres://agentfield:agentfield@localhost:5432/agentfield?sslmode=disable \
goose -dir ./migrations postgres "$AGENTFIELD_DATABASE_URL" status
Testing
go test ./...
Linting
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run
Releases
The build-single-binary.sh script creates platform-specific binaries and README artifacts. CI-driven releases are defined in .github/workflows/release.yml.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
af
command
|
|
|
agentfield-server
command
|
|
|
x25519gen
command
Command x25519gen is a standalone interop fixture: it derives an X25519 keyAgreement keypair using the same HKDF derivation and JWK encoding the DID service uses, and prints the public/private JWKs as JSON.
|
Command x25519gen is a standalone interop fixture: it derives an X25519 keyAgreement keypair using the same HKDF derivation and JWK encoding the DID service uses, and prints the public/private JWKs as JSON. |
|
internal
|
|
|
core/domain
agentfield/internal/core/domain/models.go
|
agentfield/internal/core/domain/models.go |
|
core/interfaces
agentfield/internal/core/interfaces/storage.go
|
agentfield/internal/core/interfaces/storage.go |
|
core/services
agentfield/internal/core/services/agent_service.go
|
agentfield/internal/core/services/agent_service.go |
|
embedding
Package embedding provides a pluggable text-embedding layer for the control plane's native knowledge (RAG) store.
|
Package embedding provides a pluggable text-embedding layer for the control plane's native knowledge (RAG) store. |
|
infrastructure/process
agentfield/internal/infrastructure/process/port_manager.go
|
agentfield/internal/infrastructure/process/port_manager.go |
|
infrastructure/storage
agentfield/internal/infrastructure/storage/config.go
|
agentfield/internal/infrastructure/storage/config.go |
|
knowledge
Package knowledge implements the control plane's native, scope-aware RAG knowledge store.
|
Package knowledge implements the control plane's native, scope-aware RAG knowledge store. |
|
logger
Package logger provides printf-style helpers for zerolog.
|
Package logger provides printf-style helpers for zerolog. |
|
skillkit
Package skillkit owns the skill catalog: it embeds skill content into the af binary, installs / uninstalls / lists skills against multiple coding-agent targets (Claude Code, Codex, Gemini, OpenCode, Aider, Windsurf, Cursor), and tracks state in ~/.agentfield/skills/.state.json.
|
Package skillkit owns the skill catalog: it embeds skill content into the af binary, installs / uninstalls / lists skills against multiple coding-agent targets (Claude Code, Codex, Gemini, OpenCode, Aider, Windsurf, Cursor), and tracks state in ~/.agentfield/skills/.state.json. |
|
sources
Package sources defines the trigger Source plugin interface and registry.
|
Package sources defines the trigger Source plugin interface and registry. |
|
sources/all
Package all bundles every first-party Source via blank imports.
|
Package all bundles every first-party Source via blank imports. |
|
sources/cron
Package cron implements a schedule-based LoopSource.
|
Package cron implements a schedule-based LoopSource. |
|
sources/databricks
Package databricks implements an HTTP Source for Databricks notification destination webhooks and normalizes them into AgentField inbound events.
|
Package databricks implements an HTTP Source for Databricks notification destination webhooks and normalizes them into AgentField inbound events. |
|
sources/genericbearer
Package genericbearer implements a webhook Source that authenticates inbound requests by comparing a bearer token in the Authorization header to a shared secret.
|
Package genericbearer implements a webhook Source that authenticates inbound requests by comparing a bearer token in the Authorization header to a shared secret. |
|
sources/generichmac
Package generichmac implements a configurable HMAC-SHA256 webhook Source.
|
Package generichmac implements a configurable HMAC-SHA256 webhook Source. |
|
sources/github
Package github implements the GitHub webhook Source.
|
Package github implements the GitHub webhook Source. |
|
sources/linear
Package linear implements the Linear webhook Source.
|
Package linear implements the Linear webhook Source. |
|
sources/sentry
Package sentry implements the Sentry integration-platform webhook Source.
|
Package sentry implements the Sentry integration-platform webhook Source. |
|
sources/slack
Package slack implements the Slack Events API Source.
|
Package slack implements the Slack Events API Source. |
|
sources/snowflake
Package snowflake implements a loop Source that polls Snowflake for trigger events and normalizes them into AgentField inbound events.
|
Package snowflake implements a loop Source that polls Snowflake for trigger events and normalizes them into AgentField inbound events. |
|
sources/stripe
Package stripe implements the Stripe webhook Source.
|
Package stripe implements the Stripe webhook Source. |
|
pkg
|
|
|
web
|
|
Click to show internal directories.
Click to hide internal directories.