ReqAnthropic.Sessions (ReqAnthropic v0.2.1)

Copy Markdown View Source

The Managed Agents Sessions API: run stateful agent sessions against an environment. Covers session lifecycle, event submission, event history, and the SSE event stream.

A session is event-driven:

  • Create the session with create/1, giving it an agent id and an environment id.
  • Send a user.message via send_events/3 to start work.
  • Stream the agent's activity back with stream/2, which yields parsed session/agent/span events.
  • Steer or interrupt in-flight with additional send_events/3 calls, typically user.interrupt or user.tool_confirmation.

Example

{:ok, session} =
  ReqAnthropic.Sessions.create(
    agent: "agent_01ABC...",
    environment_id: "env_01DEF..."
  )

{:ok, _} =
  ReqAnthropic.Sessions.send_events(session["id"], [
    %{type: "user.message", content: [%{type: "text", text: "List files"}]}
  ])

{:ok, stream} = ReqAnthropic.Sessions.stream(session["id"])
stream |> Enum.take(10) |> IO.inspect()

Summary

Functions

archive(id, opts \\ [])

Archive a session. Preserves history but blocks future events.

create(opts)
delete(id, opts \\ [])

Delete a session permanently. Cannot be called while the session is running.

events(id, opts \\ [])

List historical events for a session (paginated).

get(id, opts \\ [])
interrupt(id, opts \\ [])

Convenience: send an interrupt, optionally with a follow-up message.

list(opts \\ [])
send_events(id, events, opts \\ [])

Send one or more events to a session. events is a list of event maps (user.message, user.interrupt, user.custom_tool_result, user.tool_confirmation, user.define_outcome).

send_message(id, text, opts \\ [])

Convenience: send a single user text message.

stream(id, opts \\ [])

Open an SSE stream for a session and return {:ok, stream} where stream yields parsed event maps. Must be consumed in the calling process (per Req's into: :self contract).

Functions

archive(id, opts \\ [])

@spec archive(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Archive a session. Preserves history but blocks future events.

create(opts)

@spec create(keyword()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

delete(id, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Delete a session permanently. Cannot be called while the session is running.

events(id, opts \\ [])

@spec events(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

List historical events for a session (paginated).

get(id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

interrupt(id, opts \\ [])

@spec interrupt(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Convenience: send an interrupt, optionally with a follow-up message.

list(opts \\ [])

@spec list(keyword()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

send_events(id, events, opts \\ [])

@spec send_events(String.t(), [map()], keyword()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Send one or more events to a session. events is a list of event maps (user.message, user.interrupt, user.custom_tool_result, user.tool_confirmation, user.define_outcome).

send_message(id, text, opts \\ [])

@spec send_message(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Convenience: send a single user text message.

stream(id, opts \\ [])

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

Open an SSE stream for a session and return {:ok, stream} where stream yields parsed event maps. Must be consumed in the calling process (per Req's into: :self contract).