Erlang ADK documentation

View Source

This index separates user guides, behavior contracts, release operations, and historical delivery evidence. Start with the root README.md for installation and executable examples.

Release and project documents

  • CHANGELOG.md — cumulative changes from 0.3.0 through the released 0.9.0 version plus the explicitly unreleased 0.10 development section, fixes, evidence, and visible limitations.
  • TESTING.md — deterministic, paid-provider, Phoenix, browser, packaging, and audit gates.
  • TEST_LAYOUT.md — test ownership, recursive discovery, helper placement, and fixture conventions.
  • UPGRADING.md — behavior and configuration changes between delivery milestones.
  • RELEASING.md — the pre-tag, package, audit, approval, tag, and publication checklist. It does not claim that a tag or package was published.
  • Deployment asset guide — the in-development relx/OCI, closed/health/application-config modes, descriptor cap, PID1 drain, deployment OTLP bridge, Cloud Run, Helm/GKE, credential-safe Agent Runtime feasibility probe, and supply-chain contracts plus their explicit external-evidence boundaries. It also records the final local OCI and disposable Kind two-mode candidate gate without claiming Cloud/GKE or registry promotion.
  • Curated connector package guide — the sole offline all-package gate, dependency-metadata normalization boundary, and the explicit block on connector publication before core 0.10.0 exists in the target Hex repository.
  • SECURITY.md — supported versions, private reporting, deployment boundaries, secret handling, and known dependency advisories.
  • CONTRIBUTING.md — toolchains, design rules, evidence, and pull-request expectations.
  • FEATURE_PARITY.md — current ADK behavior-family status with explicit partial and adapter-owned surfaces.
  • README_EXAMPLE_COVERAGE.md — current README recipes and sanity checks mapped to prerequisites, deterministic coverage, and optional live validation.

The v0.9.0 deterministic release validation passed all 1,495 EUnit tests and all 6 deterministic Common Test cases, with warning-as-error compilation, 0 Dialyzer warnings, and 0 undefined or deprecated call/function findings from ./rebar3 xref. The Phoenix companion also passed 103 ExUnit and 40 browser/audio tests, production assets/release, and both health smokes. The complete evidence boundary is recorded in VERSION_0_9_0.md.

The VERSION_0_10_0.md milestone is IN DEVELOPMENT. It now includes the work previously proposed for 0.11/0.12: supervised local runtime profiles; schema-v2 JSON/strict-YAML Agent Config and composition; registry-only connectors; artifact streaming/GCS-compatible storage/effect reconciliation; vector/hybrid memory, policy, erasure, and a durable_local bundle-owned ingestion outbox; modern MCP; durable evaluation jobs plus simulators/statistics and canonical multi-format report parity; Developer UI graph/trace/evaluation surfaces; A2A streaming/task stores/push; and render-first deployment assets. Its pinned official MCP Python/TypeScript matrix and A2A JSON-RPC TCK have passed within the loopback scopes recorded in the candidate ledger. That ledger is development evidence, not a release record or arbitrary-peer/deployed-infrastructure claim.

Current evidence applies to the named codex/version_0.10.0 working-tree candidate, not to a reproducible commit or tag; its HEAD remains the v0.9 baseline and all v0.10 work is uncommitted. Focused durable-runtime checks passed 46/46, canonical evaluation-report parity/boundary checks passed 56, and the four-package wrapper passed 12/12 source plus 12/12 clean-extracted EUnit. The changed-candidate aggregate passed 1,826/1,826 EUnit, 6 deterministic Common Test cases with 22 expected paid-provider skips, clean compile/xref, 0 Dialyzer warnings, and 36,574/49,312 = 74.17% coverage. README checks passed 30/30 plus 4/4, all three example modules compiled with -Werror, and ExDoc, static Markdown, root Hex/verifier/extracted compile, and diff gates passed. Root artifact hashes/freshness are intentionally reported out of band. Exact scoped evidence and explicitly unrun external gates are in VERSION_0_10_0.md. These results do not change the IN DEVELOPMENT status.

Runtime and workflow guides

  • RUNTIME_SAFETY.md — process ownership, limits, cancellation, structured failures, and secret isolation.
  • DURABLE_INVOCATIONS.md — stable runs, replay, continuations, persistence, and restart behavior.
  • AMBIENT_RUNTIME.md — local events and fixed-delay scheduled invocations with bounded admission and session policy.
  • GRAPH_WORKFLOWS.md — graph/fork control flow, checkpoints, deterministic state merge, and resume limitations.
  • PLANNING_RUNTIME.md — explicit planner/executor contracts, bounded replanning, and model-native thinking.
  • CODE_EXECUTION.md — the external-sandbox requirement for model-requested code execution.

Artifacts, memory, and context

  • ARTIFACTS.md — scoped immutable versions, adapters, quotas, repair, tools, and current data-plane limits.
  • MEMORY.md — scoped retrieval/ingestion, durable local behavior, outbox semantics, erasure, and adapter boundaries.
  • CONTEXT.md — mandatory request sanitation, budgeting, selection, compaction, fingerprints, and provider prefix caching.

Providers, plugins, evaluation, and observability

  • MODEL_SUPPORT.md — adapter support tiers, remote evidence boundaries, and model/server recipes including keyless local Ollama/vLLM profiles and HTTPS gateways.
  • PROVIDER_PROFILES.md — recommended binary profile configuration for Gemini, native OpenAI Responses, native Anthropic Messages, Vertex AI, compatible Chat Completions, Gemini Live, and OpenAI Realtime, including credential and authority boundaries.
  • GEMINI_GROUNDING.md — Google Search grounding, bounded provider metadata, streaming, and failure behavior.
  • PLUGINS_OBSERVABILITY_EVALUATION.md — Runner-global plugins, trace/metric/export behavior, evaluation v2, and explicit content/privacy boundaries.
  • Phoenix companion guide — OIDC or loopback-only local authentication, same-BEAM gateways, agent runs, Live operations, browser voice, production TLS/proxy setup, and its independent release/audit gates.

Version contracts

These contracts preserve what each development milestone set out to deliver, what passed, and what remained incomplete. Unchecked items are limitations, not implicit release claims.

  • VERSION_0_3_0.md — supervised runtime, services, protocols, developer tooling, and quality foundation.
  • VERSION_0_4_0.md — agent, tool, and workflow behavior.
  • VERSION_0_5_0.md — artifacts, memory, and context.
  • VERSION_0_6_0.md — authentication, protocols, and the production-capable Phoenix companion.
  • VERSION_0_7_0.md — Gemini Live/multimodal sessions, plugins, evaluation, expanded observability, developer projections, and browser voice.
  • VERSION_0_8_0.md — model provider profiles, native OpenAI/Anthropic request adapters, compatible vendors, shared model transport, and OpenAI Realtime bidirectional sessions.
  • VERSION_0_9_0.md — definition-bound durable workflow checkpoints, graph validation/inspection and data contracts, nested continuation parity, local-compatible endpoints, and Vertex AI/ADC.
  • VERSION_0_10_0.md — IN DEVELOPMENT: the expanded 0.10 implementation and its explicit interoperability, topology, payload, reconciliation, and deployment-evidence boundaries.

Model and test terminology

The project has two separate Gemini gates:

  • REST GenerateContent/SSE and the ordinary agent default use gemini-3.1-flash-lite and ERLANG_ADK_GEMINI_REST=1.
  • Gemini Live WebSocket uses gemini-3.1-flash-live-preview and ERLANG_ADK_GEMINI_LIVE=1.

Both require GEMINI_API_KEY in the same environment as Common Test. They use network access, quota, and billable API calls, so they skip unless explicitly enabled. A skip or quota failure is never counted as a deterministic pass.

OpenAI Responses, Anthropic Messages, compatible Chat Completions, and OpenAI Realtime passed deterministic injected-transport/codec coverage in the 0.8 release gate. The 0.9 release also has deterministic Vertex and local-server fixtures, but neither is paid or arbitrary-endpoint evidence. A configured key or passing fixture must not be reported as remote-provider success. The 2026-07-17 Gemini REST and Live attempts were external credential failures, recorded separately from passing deterministic evidence; see TESTING.md.