# ReqManagedAgents v0.9.0 - Table of Contents

> Provider-agnostic Elixir client for agent runtimes — one Session loop, any loop host: server-side (Anthropic Claude Managed Agents, AWS Bedrock AgentCore) or in-process (Local, over any OpenAI-compatible chat endpoint). Your tools run locally.

## Pages

- [ReqManagedAgents](readme.md)
- [Changelog](changelog.md)

## Modules

- [ReqManagedAgents](ReqManagedAgents.md): Provider-agnostic Elixir client for agent runtimes — one Session loop, any loop host.
- [ReqManagedAgents.Agent.Handle](ReqManagedAgents.Agent.Handle.md): Handle to a provisioned, reusable agent. new/1 absorbs the Store.File JSON (string-key) round-trip.
- [ReqManagedAgents.Agent.Spec](ReqManagedAgents.Agent.Spec.md): 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.

- [ReqManagedAgents.AgentCore](ReqManagedAgents.AgentCore.md): Bedrock AgentCore entry point.
- [ReqManagedAgents.AgentCore.Client](ReqManagedAgents.AgentCore.Client.md): 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`).
- [ReqManagedAgents.AgentCore.CommandResult](ReqManagedAgents.AgentCore.CommandResult.md): Collected output of one `InvokeAgentRuntimeCommand` execution. Not an error
shape — callers branch on `exit_code` (0 = success; the command's own exit
status otherwise).

- [ReqManagedAgents.AgentCore.Converse](ReqManagedAgents.AgentCore.Converse.md): The `:agentcore_harness` wire profile: the Bedrock Converse envelope.
- [ReqManagedAgents.AgentCore.EventStream](ReqManagedAgents.AgentCore.EventStream.md): Adapter from `aws_event_stream`'s classified frames to the Converse envelope
`ReqManagedAgents.AgentCore.Converse.parse/1` consumes.
- [ReqManagedAgents.AgentCore.SigV4](ReqManagedAgents.AgentCore.SigV4.md): 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"`.
- [ReqManagedAgents.Artifact](ReqManagedAgents.Artifact.md): 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](ReqManagedAgents.Artifacts.md): One artifacts vocabulary over provider-native session storage: `list/2`,
`fetch/3`, `put/4`, `delete/3` — name-keyed and session-scoped, because a
file's NAME is the only identity the model can ever reference.
- [ReqManagedAgents.Artifacts.AgentCoreSessionStorage](ReqManagedAgents.Artifacts.AgentCoreSessionStorage.md): `ReqManagedAgents.Artifacts` store over an AgentCore harness `sessionStorage`
mount (the no-VPC filesystem type), backed by `InvokeAgentRuntimeCommand`.
- [ReqManagedAgents.Artifacts.ClaudeFiles](ReqManagedAgents.Artifacts.ClaudeFiles.md): `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>"`).
- [ReqManagedAgents.Client](ReqManagedAgents.Client.md): 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`.
- [ReqManagedAgents.Client.Behaviour](ReqManagedAgents.Client.Behaviour.md): Callback contract for the Managed Agents control plane, so consumers can swap in
a mock client in tests. `ReqManagedAgents.Client` is the live implementation.

- [ReqManagedAgents.Config](ReqManagedAgents.Config.md): 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.

- [ReqManagedAgents.Consolidate](ReqManagedAgents.Consolidate.md): Pure helpers for reconnect-with-consolidation.
- [ReqManagedAgents.Environment.Spec](ReqManagedAgents.Environment.Spec.md): 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.
- [ReqManagedAgents.Event](ReqManagedAgents.Event.md): Outbound event builders and inbound event classification for Managed Agents.
- [ReqManagedAgents.Handler](ReqManagedAgents.Handler.md): 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.
- [ReqManagedAgents.OpenTelemetry](ReqManagedAgents.OpenTelemetry.md): OTel GenAI bridge for req_managed_agents (mirrors `ReqLLM.OpenTelemetry`).
- [ReqManagedAgents.OpenTelemetry.Attributes](ReqManagedAgents.OpenTelemetry.Attributes.md): 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.

- [ReqManagedAgents.OpenTelemetry.SemConv](ReqManagedAgents.OpenTelemetry.SemConv.md): OTel GenAI semantic-convention lookups for the managed-agents (Anthropic) path.
- [ReqManagedAgents.Outcome](ReqManagedAgents.Outcome.md): 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.
- [ReqManagedAgents.Profile](ReqManagedAgents.Profile.md): 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).

- [ReqManagedAgents.Provider](ReqManagedAgents.Provider.md): 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.Providers.BedrockAgentCore](ReqManagedAgents.Providers.BedrockAgentCore.md): `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.

- [ReqManagedAgents.Providers.BedrockAgentCore.HarnessSpec](ReqManagedAgents.Providers.BedrockAgentCore.HarnessSpec.md): 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.Providers.ClaudeManagedAgents](ReqManagedAgents.Providers.ClaudeManagedAgents.md): `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.Providers.Local](ReqManagedAgents.Providers.Local.md): `ReqManagedAgents.Provider` that runs the agent loop **in-process** — `:request_response`
mode, one model call per `poll_turn/2` through a pluggable `chat_fun`.
- [ReqManagedAgents.Provisioner](ReqManagedAgents.Provisioner.md): 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.

- [ReqManagedAgents.Provisioner.Agents](ReqManagedAgents.Provisioner.Agents.md): 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.
- [ReqManagedAgents.Provisioner.Environment.Handle](ReqManagedAgents.Provisioner.Environment.Handle.md): Handle to a provisioned, reusable environment image. new/1 absorbs the Store.File JSON (string-key) round-trip.
- [ReqManagedAgents.Provisioner.Environments](ReqManagedAgents.Provisioner.Environments.md): Environments as immutable images: content-addressed by spec digest, built
once, reused forever, superseded by NEW images (never mutated), destroyed
only by explicit prune.
- [ReqManagedAgents.Provisioner.Runtime](ReqManagedAgents.Provisioner.Runtime.md): 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).

- [ReqManagedAgents.Provisioner.Runtimes](ReqManagedAgents.Provisioner.Runtimes.md): Runtime declarations for environment specs: validation, bootstrap script
rendering, and host allowlist queries.
- [ReqManagedAgents.Provisioner.Store](ReqManagedAgents.Provisioner.Store.md): 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.
- [ReqManagedAgents.Provisioner.Store.ETS](ReqManagedAgents.Provisioner.Store.ETS.md): 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).

- [ReqManagedAgents.Provisioner.Store.File](ReqManagedAgents.Provisioner.Store.File.md): 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.
- [ReqManagedAgents.SSE](ReqManagedAgents.SSE.md): Pure Server-Sent-Events frame decoder for the Managed Agents event stream.
- [ReqManagedAgents.Session](ReqManagedAgents.Session.md): The one agent loop, provider- and transport-agnostic.
- [ReqManagedAgents.SessionInfo](ReqManagedAgents.SessionInfo.md): Runtime identity of the session a callback is executing in — passed as the
optional extra argument to `c:ReqManagedAgents.Handler.handle_tool_call/4`
and `c:ReqManagedAgents.Handler.handle_event/3`.
- [ReqManagedAgents.SessionResult](ReqManagedAgents.SessionResult.md): The accumulated outcome of a whole run — what `Session.run/2` and `message/2` deliver.
- [ReqManagedAgents.SessionSupervisor](ReqManagedAgents.SessionSupervisor.md): 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`.

- [ReqManagedAgents.Stream](ReqManagedAgents.Stream.md): Long-lived SSE consumer for `GET /v1/sessions/{id}/events/stream`.
- [ReqManagedAgents.ToolResult](ReqManagedAgents.ToolResult.md): The locally-produced result of running a custom tool — what resumes the loop.
- [ReqManagedAgents.ToolSchema](ReqManagedAgents.ToolSchema.md): Jido.Action NimbleOptions schema → Anthropic custom-tool definition.
- [ReqManagedAgents.ToolUse](ReqManagedAgents.ToolUse.md): A tool call — client-side (custom, return-of-control) or server-side (observe-only).
- [ReqManagedAgents.TurnResult](ReqManagedAgents.TurnResult.md): The canonical outcome of ONE turn — what `Provider.normalize/1` returns.
- [ReqManagedAgents.Usage](ReqManagedAgents.Usage.md): Token usage — canonical summed counts + the provider's raw usage object(s) verbatim.

## Mix Tasks

- [mix req_managed_agents.agent_core.smoke](Mix.Tasks.ReqManagedAgents.AgentCore.Smoke.md): Drives the full `req_managed_agents` AgentCore Harness client stack end-to-end
as a single repeatable command — no live AWS needed.
- [mix req_managed_agents.qa_checkpoint](Mix.Tasks.ReqManagedAgents.QaCheckpoint.md): QA-CHECKPOINT — canonical proof that the Provider/Session refactor changed no observable
behavior of either provider.
- [mix req_managed_agents.qa_provisioning](Mix.Tasks.ReqManagedAgents.QaProvisioning.md): Provisioning lifecycle smoke — a runnable, deterministic proof that the full provider-agnostic
lifecycle works cohesively for BOTH providers

