@callback cancel(adapter(), String.t()) ::
  {:ok, String.t()} | {:error, AgentSessionManager.Core.Error.t()}

Cancels an in-progress run.

Providers should attempt to gracefully cancel the run. After cancellation, the run should emit a :run_cancelled event.

Parameters

• adapter - The adapter instance
• run_id - The ID of the run to cancel

Returns

• {:ok, run_id} - Cancellation initiated (run will emit cancelled event)
• {:error, Error.t()} - Cancellation failed

Examples

iex> MyAdapter.cancel(adapter, "run_123")
{:ok, "run_123"}

@callback capabilities(adapter()) ::
  {:ok, [AgentSessionManager.Core.Capability.t()]}
  | {:error, AgentSessionManager.Core.Error.t()}

Returns the list of capabilities supported by this provider.

Capabilities define what the provider can do - tools, resources, sampling modes, etc. The SessionManager uses this to validate that required capabilities are available before starting runs.

Returns

• {:ok, [Capability.t()]} - List of supported capabilities
• {:error, Error.t()} - If capabilities cannot be determined

Examples

iex> MyAdapter.capabilities(adapter)
{:ok, [
  %Capability{name: "chat", type: :tool, enabled: true},
  %Capability{name: "sampling", type: :sampling, enabled: true}
]}

@callback execute(
  adapter(),
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  execute_opts()
) :: {:ok, run_result()} | {:error, AgentSessionManager.Core.Error.t()}

Executes a run against the AI provider.

This is the main execution entry point. The adapter should:

1. Emit a :run_started event
2. Send the request to the provider
3. Emit events as responses come in (:message_received, :tool_call_started, etc.)
4. Emit :run_completed or :run_failed when done
5. Return the final result

Parameters

• adapter - The adapter instance
• run - The run to execute (contains input, session_id, etc.)
• session - The parent session (contains context, metadata)
• opts - Execution options:
  • :event_callback - Function called for each event emitted
  • :timeout - Maximum execution time in milliseconds

Returns

• {:ok, result} - Execution completed successfully
  • result.output - The final output from the provider
  • result.token_usage - Token usage statistics
  • result.events - All events emitted during execution
• {:error, Error.t()} - Execution failed

Examples

iex> callback = fn event -> Logger.info("Event: #{inspect(event)}") end
iex> MyAdapter.execute(adapter, run, session, event_callback: callback)
{:ok, %{
  output: %{content: "Hello!"},
  token_usage: %{input_tokens: 10, output_tokens: 20},
  events: [...]
}}

@callback name(adapter()) :: String.t()

Returns the unique name of this provider.

This name is used for logging, metrics, and identifying the provider in multi-provider configurations.

Examples

iex> MyAdapter.name(adapter)
"anthropic"

@callback validate_config(adapter() | module(), map()) ::
  :ok | {:error, AgentSessionManager.Core.Error.t()}

Validates provider-specific configuration.

This is called before the adapter starts to ensure all required configuration is present and valid.

Parameters

• adapter - The adapter instance (or module for static validation)
• config - Configuration map to validate

Returns

• :ok - Configuration is valid
• {:error, Error.t()} - Configuration is invalid

Examples

iex> MyAdapter.validate_config(adapter, %{api_key: "sk-..."})
:ok

iex> MyAdapter.validate_config(adapter, %{})
{:error, %Error{code: :validation_error, message: "api_key is required"}}