Skip to main content

docs/agentfield.md

Metadata​

  • Purpose: Project documentation source file.
  • Domain: documentation
  • Language: md
  • Bytes: 3277
  • Lines: 82
  • Content hash (short): b58725c8
  • Source (start): docs/agentfield.md:1
  • Source (end): docs/agentfield.md:82

Indexed Symbols​

No indexed functions/methods detected in this file.

Markdown Headings (if applicable)​

  • H1: AgentField Integration Model (line 1)
  • H2: Execution contract (line 3)
  • H2: Control plane adapter (line 9)
  • H2: Audit evidence (line 23)
  • H2: Agent topology (line 27)
  • H2: Outbox dispatcher (line 38)
  • H2: Runtime completion checks (GA gate) (line 43)
  • H2: Local integration profile (line 71)
  • H2: Production endpoint requirements (line 76)

Source Preview​

# 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.