# NOTE: This file is auto generated by OpenAPI Generator 7.22.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule Spatio.Api.Agents do
  @moduledoc """
  API calls for all endpoints tagged `Agents`.
  """

  alias Spatio.Connection
  import Spatio.RequestBuilder

  @doc """
  Create a new agent configuration.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `create_agent_request` (CreateAgentRequest): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.Agent.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec create_agent(Tesla.Env.client, Spatio.Model.CreateAgentRequest.t, keyword()) :: {:ok, Spatio.Model.ApiError.t} | {:ok, Spatio.Model.Agent.t} | {:error, Tesla.Env.t}
  def create_agent(connection, create_agent_request, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/v1/agents")
      |> add_param(:body, :body, create_agent_request)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {201, Spatio.Model.Agent},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Create a new agent-platform conversation.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:body` (CreateAgentConversationRequest): 

  ### Returns

  - `{:ok, Spatio.Model.AgentConversation.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec create_agent_conversation(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.AgentConversation.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def create_agent_conversation(connection, opts \\ []) do
    optional_params = %{
      :body => :body
    }

    request =
      %{}
      |> method(:post)
      |> url("/v1/agent/conversations")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {201, Spatio.Model.AgentConversation},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Append a message to an agent conversation.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `create_agent_message_request` (CreateAgentMessageRequest): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentMessage.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec create_agent_message(Tesla.Env.client, String.t, Spatio.Model.CreateAgentMessageRequest.t, keyword()) :: {:ok, Spatio.Model.ApiError.t} | {:ok, Spatio.Model.AgentMessage.t} | {:error, Tesla.Env.t}
  def create_agent_message(connection, id, create_agent_message_request, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/v1/agent/conversations/#{id}/messages")
      |> add_param(:body, :body, create_agent_message_request)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {201, Spatio.Model.AgentMessage},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Delete an agent configuration.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, nil}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec delete_agent(Tesla.Env.client, String.t, keyword()) :: {:ok, nil} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def delete_agent(connection, id, _opts \\ []) do
    request =
      %{}
      |> method(:delete)
      |> url("/v1/agents/#{id}")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {204, false},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Execute an action through the agent platform.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `execute_action_request` (ExecuteActionRequest): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.ExecuteActionResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec execute_agent_action(Tesla.Env.client, Spatio.Model.ExecuteActionRequest.t, keyword()) :: {:ok, Spatio.Model.ExecuteActionResponse.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def execute_agent_action(connection, execute_action_request, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/v1/agent/actions/execute")
      |> add_param(:body, :body, execute_action_request)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.ExecuteActionResponse},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Fetch one agent configuration.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.Agent.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_agent(Tesla.Env.client, String.t, keyword()) :: {:ok, Spatio.Model.ApiError.t} | {:ok, Spatio.Model.Agent.t} | {:error, Tesla.Env.t}
  def get_agent(connection, id, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agents/#{id}")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.Agent},
      {401, Spatio.Model.ApiError},
      {404, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Fetch one agent conversation.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentConversation.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_agent_conversation(Tesla.Env.client, String.t, keyword()) :: {:ok, Spatio.Model.AgentConversation.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def get_agent_conversation(connection, id, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agent/conversations/#{id}")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.AgentConversation},
      {401, Spatio.Model.ApiError},
      {404, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Identity bundle for the SessionStart hook (user + org + workspace + connected accounts) so the agent doesn't fish on its first turn. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentSessionContext.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_agent_session_context(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.ApiError.t} | {:ok, Spatio.Model.AgentSessionContext.t} | {:error, Tesla.Env.t}
  def get_agent_session_context(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agent/session-context")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.AgentSessionContext},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  List messages on an agent conversation.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentMessageListResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_agent_conversation_messages(Tesla.Env.client, String.t, keyword()) :: {:ok, Spatio.Model.AgentMessageListResponse.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def list_agent_conversation_messages(connection, id, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agent/conversations/#{id}/messages")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.AgentMessageListResponse},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  List the caller's agent-platform conversations. Distinct from `/v1/conversations` (renderer-driven sidebar persistence). 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentConversationListResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_agent_conversations(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.AgentConversationListResponse.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def list_agent_conversations(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agent/conversations")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.AgentConversationListResponse},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  List the caller's agent configurations.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.AgentListResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_agents(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.AgentListResponse.t} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def list_agents(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agents")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.AgentListResponse},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Curated featured agents (e.g. \"Claude Code\", \"Research Assistant\"). Read-only — these are surfaced by the renderer's preconfigured-picker UI. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, [%PreconfiguredAgent{}, ...]}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_preconfigured_agents(Tesla.Env.client, keyword()) :: {:ok, [Spatio.Model.PreconfiguredAgent.t]} | {:ok, Spatio.Model.ApiError.t} | {:error, Tesla.Env.t}
  def list_preconfigured_agents(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/v1/agents/preconfigured")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.PreconfiguredAgent},
      {401, Spatio.Model.ApiError}
    ])
  end

  @doc """
  Update an agent configuration.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `id` (String.t): 
  - `update_agent_request` (UpdateAgentRequest): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.Agent.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec update_agent(Tesla.Env.client, String.t, Spatio.Model.UpdateAgentRequest.t, keyword()) :: {:ok, Spatio.Model.ApiError.t} | {:ok, Spatio.Model.Agent.t} | {:error, Tesla.Env.t}
  def update_agent(connection, id, update_agent_request, _opts \\ []) do
    request =
      %{}
      |> method(:patch)
      |> url("/v1/agents/#{id}")
      |> add_param(:body, :body, update_agent_request)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.Agent},
      {401, Spatio.Model.ApiError}
    ])
  end
end