@spec approve(Wardrik.Scope.t(), String.t() | struct(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Approve a call an agent waits on

agent.decide with one approval. Recorded as the caller's.

POST /v1/agents/{agent}/interrupts/{interrupt}/approve

@spec ask(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Send an agent a message

POST /v1/agents/{agent}/messages

@spec authorization(
  Wardrik.Scope.t(),
  String.t() | struct(),
  String.t() | struct(),
  term()
) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read where a person authorizes a call

GET /v1/agents/{agent}/interrupts/{interrupt}/authorization

@spec calls(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

List the tool calls an agent is running

Answers not_found while the agent sleeps.

GET /v1/agents/{agent}/calls

@spec cancel(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Stop what an agent is doing

POST /v1/agents/{agent}/cancel

@spec clear(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Empty an agent's conversation

Answers conflict while it runs a turn or waits on a person.

DELETE /v1/agents/{agent}/conversation

@spec decide(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Approve or reject the calls an agent waits on

The decisions are taken together and recorded as the caller's. A rejection's reason is what the model is told in place of the call's answer. An approval's note is what it reads beside the answer.

POST /v1/agents/{agent}/decisions

@spec define(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Define an agent

Starts the agent the definition describes, or brings the one running to it from its next turn. A definition put again replaces the last. A key nothing here supports yet answers not_supported, naming it.

PUT /v1/agents/{agent}

@spec definition(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read an agent's definition

GET /v1/agents/{agent}/definition

@spec deny(Wardrik.Scope.t(), String.t() | struct(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Reject a call an agent waits on

agent.decide with one rejection. Recorded as the caller's.

POST /v1/agents/{agent}/interrupts/{interrupt}/deny

@spec events(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read an agent's log

GET /v1/agents/{agent}/events

@spec forget(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Forget an agent

DELETE /v1/agents/{agent}

@spec from_json(map()) :: t()

Builds one from the protocol's JSON.

@spec from_summary(map()) :: t()

Builds an agent from one item of the agents.list output.

@spec kill(Wardrik.Scope.t(), String.t() | struct(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Stop one tool call

DELETE /v1/agents/{agent}/calls/{call}

@spec move(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Move an agent to another node

Starts the agent again on node, as it was. A turn it's taking ends, and what it waits on is abandoned, so ask it again once it's moved.

POST /v1/agents/{agent}/move

@spec read(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read what an agent is doing now

GET /v1/agents/{agent}

@spec reply(Wardrik.Scope.t(), String.t() | t(), term(), keyword()) ::
  {:ok, Wardrik.Reply.t()}
  | {:waiting, [Wardrik.Interrupt.t()]}
  | {:error, Wardrik.Error.t()}

Sends the agent a message and returns its answer once the run ends.

Wardrik.Agent.reply(scope, "acme/triage", "What's on fire?")
#=> {:ok, %Wardrik.Reply{message: "msg_Xq3f...", run: "0af76519...", text: "Nothing's on fire."}}

Returns {:waiting, interrupts} if the run waits on a person. Returns {:error, %Wardrik.Error{}} if the agent can't be reached or the run fails. Takes the :timeout option of stream/4.

@spec runs(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read what an agent's runs did and cost

GET /v1/agents/{agent}/runs

@spec spawn(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Start an agent

POST /v1/agents/{agent}/spawn

@spec stop(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Stop an agent

POST /v1/agents/{agent}/stop

@spec stream(Wardrik.Scope.t(), String.t() | t(), term(), keyword()) ::
  Enumerable.t() | {:ok, reference()}

Sends the agent a message and streams the text of its answer.

scope |> Wardrik.Agent.stream("acme/triage", "What's on fire?") |> Enum.each(&IO.write/1)

The stream ends when the run ends, including when it fails. Use reply/4 to see how it ended. Raises Wardrik.Error if the agent can't be reached.

With to: pid, returns {:ok, ref} and sends pid each item as {Wardrik, ref, item}:

1. {:text, chunk}, any number of times.
2. One of {:done, %Wardrik.Reply{}}, {:waiting, interrupts} or {:failed, why}.

Options

• :to - a pid to send the answer to, in place of returning a stream.
• :timeout - milliseconds to wait for each part of the answer. Ten minutes unless set.

@spec stream_events(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  {:ok, Enumerable.t()} | :ok | {:error, Wardrik.Error.t()}

Read an agent's log, then follow new events as they arrive. Returns {:ok, stream} of {%Wardrik.Event{}, cursor} pairs.

GET /v1/agents/{agent}/events

@spec timeline(Wardrik.Scope.t(), String.t() | struct(), term()) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Read an agent's conversation as a person reads it

GET /v1/agents/{agent}/timeline

@spec to_json(t()) :: map()

Returns it as the protocol's JSON, without fields that are nil.

@spec trigger_remove(
  Wardrik.Scope.t(),
  String.t() | struct(),
  String.t() | struct(),
  term()
) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Remove one of an agent's triggers

DELETE /v1/agents/{agent}/triggers/{trigger}

@spec trigger_set(
  Wardrik.Scope.t(),
  String.t() | struct(),
  String.t() | struct(),
  term()
) ::
  term() | :ok | {:error, Wardrik.Error.t()}

Set one of an agent's triggers

Sets or changes one trigger of an agent with a definition, which keeps it; not_found where it has none. A trigger whose every and timezone stay keeps its next run.

PUT /v1/agents/{agent}/triggers/{trigger}