Skip to content

HTTP_API.md

Latest commit

 

History

History
58 lines (43 loc) · 2.33 KB

HTTP_API.md

File metadata and controls

58 lines (43 loc) · 2.33 KB
Raw

Reference HTTP API

agentkit.surfaces.api is an authenticated reference adapter around one Runtime. It demonstrates safe wiring of the core; it is not a complete identity platform or a distributed API gateway.

Secure defaults

All endpoints except /healthz fail closed until AGENTKIT_API_BEARER_TOKEN is set. For local-only experiments, AGENTKIT_API_ALLOW_INSECURE=true explicitly disables that requirement. Never use insecure mode on a shared network.

Tenant identity is server-controlled through AGENTKIT_API_TENANT_ID. The request schema rejects a client-supplied tenant, preventing callers from selecting a more permissive profile. AGENTKIT_RATE_LIMIT_PER_MIN enables a process-local per-client limit; multi-replica deployments need gateway-level distributed limiting.

The audit endpoint has no path parameter. /v1/run and /v1/audit/verify use only AGENTKIT_DB_PATH, so callers cannot create or inspect arbitrary SQLite files. Configure AGENTKIT_AUDIT_HMAC_KEY, persist the database directory, and set AGENTKIT_AUDIT_REQUIRED=true where a missing trail must abort work.

export AGENTKIT_API_BEARER_TOKEN='replace-me'
export AGENTKIT_API_TENANT_ID='acme-readonly'
export AGENTKIT_DB_PATH='data/audit.db'
export AGENTKIT_AUDIT_HMAC_KEY='replace-me-too'
export AGENTKIT_AUDIT_REQUIRED=true

uvicorn agentkit.surfaces.api:app

Approval integration

The module-level app has no approval callback, so every write tool is denied. An embedder that owns a human approval workflow can inject it:

from agentkit.surfaces.api import create_app

app = create_app(approval_fn=my_async_approval_callback)

The callback is bounded by AGENTKIT_APPROVAL_TIMEOUT_SECONDS; absence, timeout, exception, or any non-True result denies the write.

Production boundary

For an internet-facing deployment:

  • put the adapter behind OIDC/mTLS authentication and a distributed rate limiter;
  • map authenticated identity to a server-side Runtime/tenant instead of sharing one bearer token across organizations;
  • inject an external approval workflow for writes;
  • persist and back up the audit database and its high-water-mark sidecar;
  • terminate TLS at the gateway and restrict /metrics to the monitoring plane;
  • run one process per materially different registration boundary when sharing the global tool registry is unsuitable.