# ReqManagedAgents v0.1.0 - Table of Contents

> Provider-agnostic Elixir client for managed agent runtimes (Anthropic Claude Managed Agents, AWS Bedrock AgentCore) — the provider runs the loop, your tools run locally.

## Pages

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

## Modules

- [ReqManagedAgents](ReqManagedAgents.md): Provider-agnostic Elixir client for managed agent runtimes.
- [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.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.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.Consolidate](ReqManagedAgents.Consolidate.md): Pure helpers for reconnect-with-consolidation.
- [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.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.

- [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.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. ETS-backed
(process-independent); the handle is the durable artifact (persistable + reusable across
processes), so the cache is an in-process optimization, not the source of truth.

- [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.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

