Modules
Provider-agnostic Elixir client for agent runtimes — one Session loop, any loop host.
Handle to a provisioned, reusable agent. new/1 absorbs the Store.File JSON (string-key) round-trip.
A content-addressed agent definition — the managed-entity analogue of an
environment spec. name is the repository base; the digest hashes only the
identity content (system_prompt, tools, terminal_tool, model_config),
so two identically-defined agents share a digest regardless of their name.
Bedrock AgentCore entry point.
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).
Collected output of one InvokeAgentRuntimeCommand execution. Not an error
shape — callers branch on exit_code (0 = success; the command's own exit
status otherwise).
The :agentcore_harness wire profile: the Bedrock Converse envelope.
Adapter from aws_event_stream's classified frames to the Converse envelope
ReqManagedAgents.AgentCore.Converse.parse/1 consumes.
SigV4 request signing for the bedrock-agentcore AWS service, reusing the
:ex_aws_auth signer. The signer is service-parameterized, so the same call
signs both the data plane (bedrock-agentcore.<region>) and the control plane
(bedrock-agentcore-control.<region>) — pass service: "bedrock-agentcore".
A named file in a session's storage, provider-agnostic. name is the only
identity the model ever sees; ref is the provider-native identity (a CMA
file id, a sandbox path); raw is the unparsed provider record when one exists.
ReqManagedAgents.Artifacts store over an AgentCore harness sessionStorage
mount (the no-VPC filesystem type), backed by InvokeAgentRuntimeCommand.
ReqManagedAgents.Artifacts store over the Anthropic Files API, scoped to one
session. list uses the session-scoped file listing (the only way to discover
server-minted file ids for files the agent wrote); fetch/delete act on the
newest record when a name appears more than once (re-runs accumulate);
put uploads and attaches at opts[:mount_path] (default "/data/<name>").
Low-level control-plane HTTP client for Claude Managed Agents (agents, sessions,
events) over Req. The long-lived SSE event stream lives in
ReqManagedAgents.Stream.
Callback contract for the Managed Agents control plane, so consumers can swap in
a mock client in tests. ReqManagedAgents.Client is the live implementation.
The single resolution point for library configuration. Every value follows
the same priority: an explicit opts keyword, then
Application.get_env(:req_managed_agents, key), then a System.get_env
environment variable, then a default. Callers never read env directly — so
the whole config surface is one grep for Config.resolve away.
Pure helpers for reconnect-with-consolidation.
Content-addressed identity of the runtime environment an agent is provisioned
into — the environment mirror of ReqManagedAgents.Agent.Spec. config is
provider-verbatim (opaque; the library never interprets it); runtimes is
typed — the library renders it, so new/1 validates every runtime through
ReqManagedAgents.Provisioner.Runtime.new/1 before it can reach the bootstrap
renderer.
Outbound event builders and inbound event classification for Managed Agents.
Behaviour a consumer implements to plug local tool execution and event handling
into ReqManagedAgents.Session. This is the "tools stay local" seam: the
managed loop runs on Anthropic's side and calls back into handle_tool_call/3
on your node.
OTel GenAI bridge for req_managed_agents (mirrors ReqLLM.OpenTelemetry).
Pure mappers: RMA :telemetry metadata -> binary-keyed OTel GenAI (gen_ai.*)
attribute maps. No OTel SDK required. Privacy: scalar metadata + usage + tool
name only — never message content or tool input/result payloads.
OTel GenAI semantic-convention lookups for the managed-agents (Anthropic) path.
A graded-session goal: a natural-language description of what to achieve and
a rubric the provider grades the result against, optionally bounded by
max_iterations revise cycles.
Server wire-compat profile. :anthropic is identity (Anthropic cloud shape).
:jido encodes the 4 remaps proven by the jido_managed_agents handshake spike:
(1) tool-use name/input nested under content[0]/payload; (2) end_turn signalled
as status_idle + null stop_reason (gate on "agent seen"); (3) /events/stream path;
(4) pagination cursor (after vs next_page — handled in the paging layer).
Contract a streaming agent backend implements so one ReqManagedAgents.Session loop can
drive ANY provider. A provider owns its transport mode and invocation end-to-end
ReqManagedAgents.Provider for the Bedrock AgentCore backend — :request_response mode.
Each turn is one InvokeHarness call; resume re-sends the assistant toolUse + user
toolResult delta (the harness does not persist the uncommitted tool-use turn). Composes
the existing AgentCore.{Client, Converse} modules. Decoded events are additionally
delivered live to the session as {:provider_event, ev} messages while a turn streams.
provision/2's opts[:environment] carries an Environment.Spec (or a map coerced via
Environment.Spec.new/1, or nil). Its opaque config is handed to CreateHarness's
environment field VERBATIM — no per-key indexing, symmetric with how
ClaudeManagedAgents passes config straight to its wire body (filesystem mounts, custom
containers, env vars, all opaque and never interpreted by this library). Environment is
first-class (#70/#72): it reaches this provider only via opts[:environment], never the
spec, and its digest is folded into the harness name so different environments never
collide on a name.
Typed CreateHarness spec assembled by BedrockAgentCore.build_spec/2. environment is the opaque, provider-verbatim Environment.Spec.config passthrough (env vars live nested inside it, as the AWS API shapes them — there is no separate indexed field).
ReqManagedAgents.Provider for the Anthropic Managed Agents backend — :streaming mode.
A long-lived SSE stream pushes events; the client POSTs events to drive it; a turn ends on
session.status_idle. Resume POSTs a user.custom_tool_result event (no echo — the session
already holds the tool call). Composes Client, Stream, Event.
ReqManagedAgents.Provider that runs the agent loop in-process — :request_response
mode, one model call per poll_turn/2 through a pluggable chat_fun.
Hash-keyed provision cache. ensure/3 returns a cached provider handle for a given
{provider, spec}, calling provider.provision/2 only on a miss. The handle is the
durable artifact; where the {hash → handle} mapping lives is pluggable via the
ReqManagedAgents.Provisioner.Store behaviour (:store option) — in-process ETS by
default, or a persistent store (e.g. Store.File) for reuse across OS processes.
Agents as content-addressed managed entities: keyed by spec digest, created
once, reused forever, superseded by NEW specs, destroyed only by explicit
prune — the exact lifecycle Provisioner.Environments gives environments.
Handle to a provisioned, reusable environment image. new/1 absorbs the Store.File JSON (string-key) round-trip.
Environments as immutable images: content-addressed by spec digest, built once, reused forever, superseded by NEW images (never mutated), destroyed only by explicit prune.
A language runtime to install in a provisioned environment. new/1 is the
single shape+charset validation gate (the version charset closes shell
injection through the rendered bootstrap script).
Runtime declarations for environment specs: validation, bootstrap script rendering, and host allowlist queries.
Storage behaviour for the provision cache: where {spec-hash → handle} and
tag pointers live. ReqManagedAgents.Provisioner.Store.ETS (default) keeps
today's in-process semantics; ReqManagedAgents.Provisioner.Store.File
persists across OS processes for CLI/mix-task/cron consumers.
Default in-process store — a named public ETS table. Process-independent within one BEAM; empty in every fresh OS process (the original cache semantics, unchanged).
Persistent JSON-file store: provision handles and tags survive OS-process restarts (CLI tools, mix tasks, cron). One flat JSON object per file; writes are atomic (temp file + rename). Single-writer assumption: this is a workstation/task-runner store, not a concurrent-fleet store. A missing or corrupt file is treated as empty (with a logged warning) — the durable provider resources are recoverable regardless.
Pure Server-Sent-Events frame decoder for the Managed Agents event stream.
The one agent loop, provider- and transport-agnostic.
Runtime identity of the session a callback is executing in — passed as the
optional extra argument to ReqManagedAgents.Handler.handle_tool_call/4
and ReqManagedAgents.Handler.handle_event/3.
The accumulated outcome of a whole run — what Session.run/2 and message/2 deliver.
Optional DynamicSupervisor for running one ReqManagedAgents.Session per
child. Add it to your supervision tree, then start_child/1 with the same opts
you'd pass to ReqManagedAgents.Session.start_link/2.
Long-lived SSE consumer for GET /v1/sessions/{id}/events/stream.
The locally-produced result of running a custom tool — what resumes the loop.
Jido.Action NimbleOptions schema → Anthropic custom-tool definition.
A tool call — client-side (custom, return-of-control) or server-side (observe-only).
The canonical outcome of ONE turn — what Provider.normalize/1 returns.
Token usage — canonical summed counts + the provider's raw usage object(s) verbatim.
Mix Tasks
Drives the full req_managed_agents AgentCore Harness client stack end-to-end
as a single repeatable command — no live AWS needed.
QA-CHECKPOINT — canonical proof that the Provider/Session refactor changed no observable behavior of either provider.
Provisioning lifecycle smoke — a runnable, deterministic proof that the full provider-agnostic lifecycle works cohesively for BOTH providers
Maintainer task: runs each wired live scenario against a real provider,
redacts the captured request/response bodies, and writes them into
$RMA_CORPUS_DIR/<surface>/{requests,responses}/<name>.json, stamping
$RMA_CORPUS_DIR/<surface>/manifest.json.
Maintainer task: mirrors the bedrock-agentcore and bedrock-agentcore-control
botocore service-2.json models from boto/botocore into
$RMA_CORPUS_DIR/agentcore/model/, and pins the upstream commit plus
per-file SHA256 in $RMA_CORPUS_DIR/agentcore/manifest.json.