diff --git a/docs.json b/docs.json index 1aa5e4ea71..3b673ccee2 100644 --- a/docs.json +++ b/docs.json @@ -624,6 +624,7 @@ "pages": [ "weave/guides/integrations/openai_agents", "weave/guides/integrations/openai-realtime-audio", + "weave/guides/integrations/bedrock_agents", "weave/guides/integrations/claude_agent", "weave/guides/integrations/claude_code", "weave/guides/integrations/langchain", diff --git a/weave/guides/integrations/bedrock_agents.mdx b/weave/guides/integrations/bedrock_agents.mdx new file mode 100644 index 0000000000..45d509bae7 --- /dev/null +++ b/weave/guides/integrations/bedrock_agents.mdx @@ -0,0 +1,117 @@ +--- +title: Bedrock Agents +description: "Trace Amazon Bedrock Agents invocations with Weave, capturing agent inputs, foundation model usage, and completion output." +--- + +[Amazon Bedrock Agents](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) let you build managed AI agents on AWS that orchestrate foundation models, knowledge bases, and action groups. Weave traces calls to the `bedrock-agent-runtime` client so you can inspect each `invoke_agent` invocation, including the foundation model, token usage, session ID, and the agent's response. + + +The Weave TypeScript SDK doesn't currently Bedrock Agent integration. + + +## Prerequisites + +- A W&B API key. For more information, see [API keys](/platform/app/settings-page/user-settings#api-keys). +- AWS credentials configured for an account with access to Bedrock Agents (see [Authentication](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)). +- An existing Bedrock agent and alias. Note the `agentId` and `agentAliasId`. You can return a list of agents associated with your ID by running the following AWS CLI command, replacing `` with the region slug your agent resides in: + + ```bash + aws bedrock-agent list-agents --region us-east-1 + ``` + +## Installation + +Install Weave and the AWS SDK: + +```bash +pip install weave boto3 +``` + +## Trace `invoke_agent` calls + +Create a `bedrock-agent-runtime` client and pass it to `patch_client`. Weave detects the client type and wraps the `invoke_agent` method. After patching, use the client as you normally would. + +```python lines highlight="15-17" +import boto3 + +import weave +from weave.integrations.bedrock import patch_client + +weave.init("your-team-name/bedrock-agents-demo") + +# Create and patch the Bedrock Agents runtime client. +bedrock_agent_client = boto3.client("bedrock-agent-runtime", region_name="us-east-1") +patch_client(bedrock_agent_client) + +# Invoke the agent. Set `enableTrace=True` so Weave can capture the underlying +# foundation model and token usage from the orchestration trace events. +response = bedrock_agent_client.invoke_agent( + agentId="[YOUR-AGENT-ID]", + agentAliasId="[YOUR-AGENT-ALIAS-ID]", + sessionId="[YOUR-SESSION-ID]", + inputText="What is the capital of France?", + enableTrace=True, +) + +# Consume the streaming completion to assemble the final response text. +final_text = "" +for event in response["completion"]: + chunk = event.get("chunk") + if chunk and "bytes" in chunk: + final_text += chunk["bytes"].decode("utf-8") + +print(final_text) +``` + +Each `invoke_agent` call appears in the Weave UI as a `BedrockAgentRuntime.invoke_agent` trace. The trace records: + +- The agent inputs (`agentId`, `agentAliasId`, `sessionId`, `inputText`). +- The extracted assistant text from the completion event stream. +- The underlying foundation model used by the agent (extracted from the orchestration trace). +- Token usage (`prompt_tokens`, `completion_tokens`, `total_tokens`) when reported by the agent. + +Foundation model and token usage are extracted from `orchestrationTrace` events, which Bedrock only emits when `invoke_agent` is called with `enableTrace=True`. Without this flag, traces still capture the inputs and the generated response text, but the foundation model falls back to `bedrock-agent:` and token counts are unavailable. + +## Wrap an agent call with `weave.op` + +To group an `invoke_agent` call with related logic, such as preprocessing, postprocessing, or chained API calls, wrap your function with `@weave.op`. Weave nests the patched `invoke_agent` trace inside the parent op. + +```python lines +@weave.op +def ask_agent(question: str, session_id: str) -> str: + response = bedrock_agent_client.invoke_agent( + agentId="[YOUR-AGENT-ID]", + agentAliasId="[YOUR-AGENT-ALIAS-ID]", + sessionId=session_id, + inputText=question, + enableTrace=True, + ) + text = "" + for event in response["completion"]: + chunk = event.get("chunk") + if chunk and "bytes" in chunk: + text += chunk["bytes"].decode("utf-8") + return text + + +answer = ask_agent("Summarize today's open support tickets.", session_id="session-1") +``` + +## Multi-turn conversations + +Bedrock Agents preserve conversation state on the service side when you reuse a `sessionId`. To group multiple turns into a single trace in the Weave UI, wrap the turns in `weave.thread`: + +```python lines +with weave.thread("support-conversation") as t: + for prompt in [ + "I can't log in to my account.", + "I already tried resetting my password.", + ]: + ask_agent(prompt, session_id=t.thread_id) +``` + +Weave displays each turn in the UI as individual rows in the Threads view. + +## View traces + +When you run the example, Weave prints a link to the project dashboard. Open the link to inspect the agent inputs, foundation model, token usage, and the generated response for each `invoke_agent` call.