Onboarding Guide: Elixir ADK Project

For New AI Agents / Developers

This document provides everything needed to pick up the Elixir ADK project.

1. What Is This Project?

We are building an Elixir/OTP port of Google's Agent Development Kit (ADK). The Google ADK is a framework for building AI agents that can use tools, orchestrate sub-agents, manage sessions, and communicate with other agents.

Google provides the ADK in Python (reference), TypeScript, Go, and Java. We are creating the Elixir implementation.

Note: The A2A (Agent-to-Agent) protocol is a separate package at github.com/JohnSmall/a2a_ex. It depends on this ADK package via {:adk_ex, "~> 1.0"}.

Note: Example A2A applications are at github.com/JohnSmall/a2a_ex_examples. They demonstrate two-agent cooperation using the A2A protocol (research+report, code+review, data+viz).

2. Current Status

All 5 phases are COMPLETE. The project lives at github.com/JohnSmall/adk_ex. Database persistence is in a separate package at github.com/JohnSmall/adk_ex_ecto.

What's Built

Phase 1: Foundation (75 tests)

Phase 2: Runner + Tool System + LLM Agent (+63 tests = 138 total)

Phase 3: Orchestration Agents + Agent Transfer (+30 tests = 168 total)

Phase 4: Memory, Artifacts, and Telemetry (+49 tests = 217 total)

Phase 5: Plugins, Toolsets, and Database Sessions (+23 tests = 240 total, +21 in adk_ex_ecto)

Database Sessions (separate package: adk_ex_ecto, 21 tests)

Test Coverage

• adk_ex: 240 tests passing (75 + 63 + 30 + 49 + 23)
• adk_ex_ecto: 21 tests passing
• 6 integration tests (Gemini + Claude + OpenAI, excluded by default)
• Credo: clean (both packages)
• Dialyzer: clean (both packages)

Project Status

All 5 phases are complete. See docs/implementation-plan.md for full details.

3. Key Resources

Project Resources

External Documentation

4. Architecture Quick Reference

Core Execution Model

User Message -> Runner -> Agent -> Flow -> LLM
                  |          |        |       |
              [plugins]  [plugins] [plugins]  |
                  |          |     [tool calls loop]
                  |          |     [agent transfer]
                  |          |     [toolset resolution]
                  |          |        |
               [commits events + state to Session]
                  |
               [yields Events to application]

Execution Flow Detail

Runner.run/5
  |-- Get/create session from SessionService (via runner.session_module)
  |-- [plugin: on_user_message] (may modify user content)
  |-- Append user message event
  |-- [plugin: before_run] (may short-circuit entire run)
  |-- Find agent to run (transfer check -> history scan -> root)
  +-- LlmAgent.run/2
        |-- [plugin: before_agent] -> [before_agent_callbacks] (may short-circuit)
        |-- Flow.run/2 (Stream.resource/3 loop)
        |     |-- Resolve toolsets (dynamic tool providers)
        |     |-- Build LlmRequest via 5 processors:
        |     |     Basic -> ToolProcessor -> Instructions -> AgentTransfer -> Contents
        |     |-- [plugin: before_model] -> [before_model_callbacks] (may short-circuit)
        |     |-- Model.generate_content/3 (Gemini/Claude/LiteLlm/Mock)
        |     |-- [plugin: after_model] -> [after_model_callbacks] (may replace)
        |     |-- If function_calls in response:
        |     |     [plugin: before_tool] -> [before_tool] -> Tool.run/3
        |     |     -> maybe_set_transfer -> [plugin: after_tool] -> [after_tool]
        |     |     If transfer_to_agent set: run target agent (maybe_run_transfer)
        |     |     Build tool response event -> loop back to LLM
        |     +-- If text response (final): emit event, halt
        |-- [plugin: after_agent] -> [after_agent_callbacks] (may short-circuit)
        +-- If output_key: save text to state_delta
  |-- For each event: [plugin: on_event] (may modify)
  +-- [plugin: after_run] (notification)

Agent Types

Callback Points

All callbacks return {value | nil, updated_context}. Nil = continue, non-nil = short-circuit.

Plugin hooks (Phase 5): Plugins use the same callback signatures but run before agent callbacks. If a plugin returns non-nil, agent callbacks are skipped entirely. Additional plugin-only hooks: on_user_message, before_run, after_run (notification only), on_event.

State Prefixes

5. Elixir/OTP Design Patterns Used

Package Naming

• Hex package name: adk_ex (OTP app: :adk_ex)
• Module names: ADK.* (module prefix is independent of hex name, like phoenix uses Phoenix.*)
• Source paths: lib/adk/, test/adk/ (unchanged)

• Telemetry events: [:adk_ex, :llm | :tool, :start | :stop | :exception]

• Database persistence is a separate package: adk_ex_ecto (keeps core lightweight)

Critical Gotchas

1. Compile order: Define nested/referenced modules BEFORE parent modules in the same file (e.g., Event.Actions before Event)
2. MapSet + dialyzer: Avoid MapSet — use %{key => true} maps + Map.has_key?/2 instead
3. Credo nesting: Max depth 2 — extract inner logic into helper functions
4. Mock model: Use Mock.new(responses: [...]) NOT bare %Mock{} — needs Agent process for state
5. Behaviour dispatch: ADK.Agent has NO module functions — call agent.__struct__.run(agent, ctx) or the implementing module directly
6. Test module names: Use unique names to avoid cross-file collisions
7. OTel span testing: config/test.exs configures otel_simple_processor. In test setup, call :otel_simple_processor.set_exporter(:otel_exporter_pid, self()) to route spans to the test process. Span name is at elem(span, 6) (not 2) in the Erlang span record. No app restart needed.
8. Dialyzer unreachable branches: If a function always returns {:ok, _}, don't pattern match {:error, _} — dialyzer flags it
9. FunctionTool field: Use handler: not function: in FunctionTool.new/1
10. Plugin nil safety: All Plugin.Manager.run_* functions accept nil as first arg — no nil checks needed at call sites
11. SQLite in-memory testing: Don't use Ecto sandbox with pool_size 1. Clean tables in setup instead.
12. OpenTelemetry dep: {:opentelemetry, "~> 1.5"} must NOT have only: [:dev, :test] — it's needed at compile time in all environments (the require OpenTelemetry.Tracer in ADK.Telemetry needs it).
13. Dep name must match app name: When other projects depend on this package, they must use {:adk_ex, path: "..."} (not {:adk, ...}). Mix fails to resolve code paths when the dep name doesn't match the app name :adk_ex.

6. Development Workflow

Running Tests

mix test                                        # Run all unit tests (240)
mix test test/integration/ --include integration # Run integration tests
mix test --trace                                 # Run with verbose output
mix credo                                        # Static analysis
mix dialyzer                                     # Type checking

Conventions

• Module names: ADK.Component.SubComponent (e.g., ADK.Agent.LlmAgent)
• Behaviours: Define in dedicated files (e.g., agent.ex, model.ex, tool.ex)
• Structs: defstruct + @type t :: %__MODULE__{} typespecs

• Callbacks: Return {value | nil, context} — nil = continue, non-nil = short-circuit

• Errors: {:ok, result} / {:error, reason} tuples
• Tests: Mirror lib/ structure under test/; use async: true unless shared state
• Use Mock.new(responses: [...]) for test models
• Verify all changes: mix test && mix credo && mix dialyzer

7. Quick Commands

mix test           # Run tests
mix credo          # Static analysis
mix dialyzer       # Type checking
iex -S mix         # Interactive shell
mix clean && mix compile  # Clean build

8. Key Contacts / Context

• Project owner: John Small (jds340@gmail.com)
• ADK Elixir project: github.com/JohnSmall/adk_ex
• A2A Elixir project: github.com/JohnSmall/a2a_ex
• A2A Examples: github.com/JohnSmall/a2a_ex_examples