Skip to main content

docs/agentfield.md

Imported Content​

AgentField Integration Model

Execution contract​

  • Gateway endpoint: POST /api/v1/execute/{agent}.{reasoner}
  • Request payload includes workspaceId, optional clientId, correlationId, callbackUrl, and freeform input
  • Response returns async execution handle with executionId

Control plane adapter​

apps/gateway/src/services/agentfield-client.ts provides strict dispatch behavior:

  1. Dispatch forwards execution to AGENTFIELD_URL.
  2. Dispatch failures return 502 (no gateway-side execution fallback).
  3. Staging/production guardrails block agentfield-mock URL usage.

Optional configuration:

  • AGENTFIELD_EXECUTE_PATH_TEMPLATE (default /api/v1/execute/{agent}.{reasoner})
  • AGENTFIELD_TIMEOUT_MS (default 15000)
  • AGENTFIELD_WEBHOOK_SECRET (required when REQUIRE_WEBHOOK_SIGNATURES=true, default in staging/prod)

Audit evidence​

apps/gateway/src/services/audit.ts creates a signed audit credential per execution using payload hash + HMAC signature with key ID metadata.

Agent topology​

See agents/agentfield.topology.yaml for event routing and workspace isolation assumptions.

Staging/production runtime expectation:

  • AgentField control plane reachable over TLS.
  • Agent execution worker/node pool deployed (not control-plane only).
  • Launch catalog agents registered and visible via GET /api/v1/agent-runtime/agents.
  • Queue/backpressure and worker heartbeat health surfaced via GET /api/v1/agent-runtime/health and /queues.

Outbox dispatcher​

  • Routed telemetry actions are persisted to outbox_events.
  • Run pnpm --filter @anchor/gateway worker:outbox to dispatch queued events to AgentField reasoners.

Runtime completion checks (GA gate)​

Use these APIs to verify effective runtime operations:

  • GET /api/v1/agent-runtime/health
  • GET /api/v1/agent-runtime/queues
  • GET /api/v1/agent-runtime/failures
  • GET /api/v1/agent-runtime/agents
  • POST /api/v1/agent-runtime/smoke
  • POST /api/v1/agent-runtime/outbox-failures/{id}/retry
  • POST /api/v1/agent-runtime/job-failures/{id}/retry

Acceptance criteria:

  1. Control plane probe returns reachable status.
  2. Gateway/outbox/job worker heartbeats are fresh and not stale.
  3. Queue depth remains within workspace SLO.
  4. Failure buckets are visible and actionable with operator retry controls.
  5. Every launch agent appears in runtime catalog with execution counters.
  6. Smoke dispatch can execute one or all launch agents and persist audit evidence.
  7. Staging/prod overlays keep agent runtime enabled and worker min replicas > 0 for outbox/job loops.

Workflow controls:

  • GET /api/v1/workflow-executions/{id} for callback/evidence detail.
  • POST /api/v1/workflow-executions/{id}/retry.
  • POST /api/v1/workflow-executions/{id}/cancel.

Local integration profile​

  • apps/agentfield-mock exists for local development and contract testing only.
  • Production deployment target is a self-hosted AgentField control plane/workers stack.

Production endpoint requirements​

  • AGENTFIELD_URL is required in staging/production.
  • AGENTFIELD_URL must use https:// in staging/production.
  • AGENTFIELD_URL must not target agentfield-mock.
  • AGENTFIELD_WEBHOOK_SECRET must be present when REQUIRE_WEBHOOK_SIGNATURES=true.