[bot] Instrument aws-sdk-bedrockagentruntime (86K weekly downloads)

先从 lib/braintrust/contrib.rb 中注册的现有集成以及 lib/braintrust/contrib/ 下的目录开始，然后检查 Appraisals 和 braintrust.gemspec，了解依赖和测试模式。围绕 Aws::BedrockAgentRuntime::Client 定义集成，尤其是 invoke_agent 及其事件流；完成内容应包括对所请求的 agent 执行面的插桩，以及对生成的 span 和输出的覆盖。

Summary

The aws-sdk-bedrockagentruntime gem is the official, auto-generated AWS SDK client for Agents for Amazon Bedrock Runtime — the agent-execution/orchestration layer of Bedrock, distinct from raw model invocation. It exposes a clear agent-run execution API (invoke_agent) with built-in reasoning-trace support, and is not instrumented by this SDK.

This is a different gem/service from aws-sdk-bedrockruntime (already tracked as a gap in #152, which covers converse/invoke_model raw model calls only). aws-sdk-bedrockagentruntime sits one layer up: it drives a configured Bedrock Agent through a multi-step reasoning/tool-use/knowledge-base-retrieval loop and returns citations plus an optional step-by-step trace — squarely an agent-run/tracing execution surface, not CRUD/admin.

What is missing

No instrumentation exists for any aws-sdk-bedrockagentruntime execution surface. Key API:

• client.invoke_agent(agent_id:, agent_alias_id:, session_id:, input_text:, enable_trace:, end_session:, session_state:, ...) — Drives one turn of a Bedrock Agent's reasoning loop (action-group/tool invocation, knowledge-base retrieval, orchestration). Returns an event stream of chunk (final response bytes), trace (the agent's step-by-step reasoning when enable_trace: true), and attribution/citation events. This is the primary agent-execution entry point — analogous to an agent "run" call in other agent frameworks this SDK could instrument.
• client.invoke_agent_generate_query, client.optimize_prompt — related generative execution helpers on the same client.

What a span should capture

• Input: input_text, session_id, agent_id/agent_alias_id, session_state (session/prompt attributes, return-of-control results)
• Metadata: provider (aws-bedrock-agent), enable_trace, end_session
• Output: final response text (from chunk events), citations/attribution
• Trace/child spans: orchestration steps, action-group (tool) invocations, and knowledge-base retrievals surfaced via trace events when enable_trace: true — a natural mapping to this SDK's existing span-tree model for tool calls

Weekly downloads

Weekly downloads: approximately 86K (as of 2026-10-14; ClickGems “last week”; source https://clickgems.clickhouse.com/dashboard/aws-sdk-bedrockagentruntime).

Additional signal: current version 1.78.0 (per https://rubygems.org/api/v1/gems/aws-sdk-bedrockagentruntime.json, checked 2026-08-10), part of the AWS SDK for Ruby's continuous auto-generated release train; total downloads 10,650,314.

Braintrust docs status

not_found — Checked https://www.braintrust.dev/docs/integrations/sdk-integrations (lists only OpenAI, Anthropic, Ruby LLM/ruby-openai for Ruby-relevant tracing integrations, plus a separate "Agent frameworks" section listing OpenAI Agents SDK, Claude Agent SDK, LangGraph, CrewAI, AutoGen, Google ADK, Strands Agents SDK, etc. — no AWS Bedrock Agents entry in either list) and https://www.braintrust.dev/docs generally. No mention of Bedrock Agents, BedrockAgentRuntime, or invoke_agent anywhere in Braintrust's documentation. (Issue #152 notes Braintrust's proxy lists Bedrock as a supported model provider, but that is unrelated to this agent-orchestration API.)

Upstream sources

• Official AWS SDK for Ruby (monorepo): https://github.com/aws/aws-sdk-ruby
• RubyGems: https://rubygems.org/gems/aws-sdk-bedrockagentruntime
• API reference: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockAgentRuntime/Client.html
• InvokeAgent operation docs: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html
• Example usage: https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-agent-runtime_example_bedrock-agent-runtime_InvokeAgent_section.html

Braintrust docs sources checked

• https://www.braintrust.dev/docs/integrations/sdk-integrations
• https://www.braintrust.dev/docs

Local repo files inspected

• lib/braintrust/contrib.rb — registers only 4 integrations: OpenAI, RubyOpenAI, RubyLLM, Anthropic. No AWS/Bedrock integration of any kind.
• lib/braintrust/contrib/ — contains only openai/, ruby_openai/, ruby_llm/, anthropic/, and rails/ directories. No bedrock or aws directory.
• Appraisals — no appraisal scenarios for aws-sdk-bedrockagentruntime or any AWS gem
• braintrust.gemspec — no mention of aws or bedrock
• Grep for bedrock, Bedrock, invoke_agent across lib/braintrust/ returns zero matches
• Confirmed issue #152 (aws-sdk-bedrockruntime-not-instrumented) only covers converse/converse_stream/invoke_model/async-invoke on the separate Aws::BedrockRuntime::Client — it does not mention BedrockAgentRuntime or invoke_agent, so this is a distinct, non-duplicate gap.