A2aEngine.Handler behaviour (a2a_engine v0.1.0)

Contract for the A2A request handler — the module that actually fulfils JSON-RPC method calls once the transport has decoded + authenticated.

The handler is transport-agnostic: both A2aEngine.Transport.Http and A2aEngine.Transport.BeamNative dispatch to the same handler contract.

Hosts implement this behaviour in their own module (e.g. MyApp.A2A.Broker) and pass it to transports via opts.

Callbacks

handle_request/3 — for unary methods (message/send, tasks/get, tasks/cancel, tasks/pushNotificationConfig/*, agent/getAuthenticatedExtendedCard). Returns {:ok, result} on success or {:error, error_map} on failure.
handle_stream/4 — for streaming methods (message/stream, tasks/resubscribe). Receives an emit callback that pushes events back to the caller. Returns {:ok, final_result} when the stream completes cleanly, or {:error, error_map} on failure.

Method dispatch

Transports call dispatch/4 (this module) which pattern-matches known A2A streaming methods to handle_stream/4 and everything else to handle_request/3. Hosts don't need to write that wiring themselves.

Summary

Types

context()

emit_fn()

error_map()

method()

params()

Callbacks

handle_request(method, params, context)

handle_stream(method, params, context, emit_fn)

Functions

dispatch(handler_mod, decoded_request, context, emit_fn \\ nil)

Dispatch a decoded JSON-RPC request to the right handler callback.

streaming?(method)

Whether a method is an A2A streaming method (message/stream or tasks/resubscribe).

Types

context()

@type context() :: %{
  :auth => A2aEngine.Auth.auth_context(),
  :id => String.t() | integer() | nil,
  optional(atom()) => any()
}

emit_fn()

@type emit_fn() :: (map() -> :ok)

error_map()

@type error_map() :: %{
  :code => integer(),
  :message => String.t(),
  optional(:data) => map()
}

method()

@type method() :: String.t()

params()

@type params() :: map() | nil

Callbacks

handle_request(method, params, context)

@callback handle_request(method(), params(), context()) ::
  {:ok, term()} | {:error, error_map()}

handle_stream(method, params, context, emit_fn)

@callback handle_stream(method(), params(), context(), emit_fn()) ::
  {:ok, term()} | {:error, error_map()}

Functions

dispatch(handler_mod, decoded_request, context, emit_fn \\ nil)

@spec dispatch(module(), map(), context(), emit_fn() | nil) ::
  {:ok, term()} | {:error, error_map()} | {:streaming, term()}

Dispatch a decoded JSON-RPC request to the right handler callback.

Streaming methods go to handle_stream/4 with the provided emit_fn; all other methods go to handle_request/3.

streaming?(method)

@spec streaming?(method()) :: boolean()

Whether a method is an A2A streaming method (message/stream or tasks/resubscribe).