ReqManagedAgents.AgentCore.Client (ReqManagedAgents v0.3.0)

SigV4-signed REST client for AWS AgentCore (bedrock-agentcore). Covers the control-plane harness lifecycle (create_harness/get_harness/delete_harness), the AgentCore Identity token-vault (create_api_key_credential_provider), and the data-plane invoke_harness (returns a decoded vnd.amazon.eventstream).

Infra-agnostic: it knows AgentCore's model-config surface, nothing about what sits behind a liteLlmModelConfig.apiBase. Build with new/1; pass as the first arg to every call. Transport is injectable via :req_options for tests.

The invoke data plane streams incrementally: receive_timeout on this struct governs control-plane calls only, while invoke_harness/2 uses the per-invoke :idle_timeout (default 300_000 ms) as an inter-chunk liveness guard — a healthy turn may run arbitrarily long; only silence fails it.

Summary

Types

t()

Functions

create_api_key_credential_provider(c, map)

create_harness(c, spec)

delete_harness(c, id)

get_harness(c, id)

invoke_agent_runtime_command(c, inv)

Data-plane InvokeAgentRuntimeCommand — run a shell command inside the session's microVM (no model loop, no token cost) and collect its streamed output.

invoke_harness(c, inv)

Data-plane InvokeHarness. Sends messages with harnessArn in the query string and the required X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header. Returns the decoded event-stream maps. Resume is just another call with the resume messages (the profile assembles them).

list_harnesses(c)

ListHarnesses (control plane). Returns the decoded body %{"harnesses" => [%{"harnessName", "harnessId", "arn", "status", ...}], "nextToken" => ...}. Used to recover an existing harness by name (idempotent provisioning) when a CreateHarness collides with a previously-created harness of the same name.

new(opts \\ [])

Types

t()

@type t() :: %ReqManagedAgents.AgentCore.Client{
  base_url: term(),
  control_base_url: term(),
  credentials: term(),
  receive_timeout: term(),
  req_options: term(),
  service: term()
}

Functions

create_api_key_credential_provider(c, map)

@spec create_api_key_credential_provider(t(), map()) ::
  {:ok, map()} | {:error, term()}

create_harness(c, spec)

@spec create_harness(t(), map()) :: {:ok, map()} | {:error, term()}

delete_harness(c, id)

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

get_harness(c, id)

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

invoke_agent_runtime_command(c, inv)

@spec invoke_agent_runtime_command(t(), map()) ::
  {:ok, ReqManagedAgents.AgentCore.CommandResult.t()} | {:error, term()}

Data-plane InvokeAgentRuntimeCommand — run a shell command inside the session's microVM (no model loop, no token cost) and collect its streamed output.

inv requires :agent_runtime_arn (the harness/runtime ARN — it rides the URI path), :runtime_session_id, and :command. Optional: :timeout_seconds (server-side cap, service default 300, max 3600), :idle_timeout (inter-chunk liveness guard, default 300_000 ms), :on_output (fn (:stdout | :stderr, chunk) called per delta, in order), :qualifier (endpoint name).

Returns {:ok, %ReqManagedAgents.AgentCore.CommandResult{}} — a non-zero exit_code is a RESULT, not an error. Transport/stream failures return {:error, term()}.

invoke_harness(c, inv)

@spec invoke_harness(t(), map()) :: {:ok, [map()]} | {:error, term()}

Note: AWS requires runtimeSessionId to be at least 33 characters long (pattern [a-zA-Z0-9][a-zA-Z0-9-_]*, max 100). The client passes it through as-is — the caller is responsible for supplying a conforming value.

list_harnesses(c)

@spec list_harnesses(t()) :: {:ok, map()} | {:error, term()}

new(opts \\ [])

@spec new(keyword()) :: t()