@spec actions(t()) :: ADK.EventActions.t()

Get the event actions (state deltas, artifact deltas, auth requests).

@spec get_credential(t(), String.t(), ADK.Auth.Credential.t(), keyword()) ::
  {:ok, ADK.Auth.Credential.t()} | :needs_auth | {:error, term()}

Get a ready-to-use credential, running OAuth2 exchange or refresh as needed.

This is the recommended way to obtain credentials in tool implementations. It uses ADK.Auth.CredentialManager to orchestrate the full lifecycle:

1. Simple credentials (api_key, http_bearer) → returned immediately
2. Stored credential → refreshed if near-expiry, returned
3. Auth-code credential → exchanged for tokens, stored, returned
4. Client-credentials capable → exchanges automatically, returned
5. No stored + no way to get one → returns :needs_auth

When :needs_auth is returned, call request_credential/2 to signal to the runner that user authentication is required.

Example

def run(tool_context, params) do
  case ADK.ToolContext.get_credential(tool_context, "github_token", raw_cred) do
    {:ok, cred} ->
      make_github_api_call(cred.access_token, params)

    :needs_auth ->
      auth_config = ADK.Auth.Config.new(
        credential_type: :oauth2,
        provider: "github",
        scopes: ["repo"]
      )
      {:ok, tc2} = ADK.ToolContext.request_credential(tool_context, auth_config)
      {:auth_required, tc2}

    {:error, reason} ->
      {:error, reason}
  end
end

Options

• :redirect_uri — used during auth code exchange
• :refresh_buffer — seconds before expiry for proactive refresh (default: 300)
• :http_opts — extra options for token requests

@spec get_state(t(), term(), term()) :: term()

Read a value from session state.

@spec has_credential?(t(), String.t()) :: boolean()

Check if a credential exists in the credential service.

@spec list_artifacts(t()) :: {:ok, [String.t()]} | {:error, term()}

List artifact filenames for the current session.

@spec load_artifact(t(), String.t(), keyword()) ::
  {:ok, map()} | :not_found | {:error, term()}

Load an artifact by filename.

Options:

• :version — specific version to load (default: latest)

@spec load_credential(t(), String.t()) ::
  {:ok, ADK.Auth.Credential.t()} | :not_found | {:error, term()}

Load a credential from the credential service (raw — no exchange/refresh).

Returns {:ok, credential} or :not_found or {:error, reason}.

For a fully managed credential (auto-exchange + auto-refresh), see get_credential/3.

@spec new(ADK.Context.t(), String.t(), map() | module()) :: t()

Create a tool context from an invocation context.

@spec put_state(t(), term(), term()) :: {:ok, t()} | {:error, :no_session}

Write a value to session state and track the delta.

@spec request_credential(t(), ADK.Auth.Config.t()) :: {:ok, t()} | {:error, term()}

Request a credential for the current tool call.

This records the auth config in event actions so the runner can surface an auth challenge to the user/client. Only works in tool context (requires function_call_id).

@spec save_artifact(t(), String.t(), map(), keyword()) ::
  {:ok, non_neg_integer(), t()} | {:error, term()}

Save an artifact and track the version in event actions.

Returns {:ok, version, updated_context} on success. Returns {:error, :no_artifact_service} if no artifact service is configured.

@spec save_credential(t(), String.t(), ADK.Auth.Credential.t()) ::
  :ok | {:error, term()}

Save a credential to the credential service.

@spec transfer_to_agent(t(), String.t()) :: ADK.Event.t()

Request transfer to another agent by name.

Returns an event with a transfer action that the runner will handle.