AWS bedrock-agentcore documentation change
Summary
Updated observability documentation to clarify automatic OpenTelemetry instrumentation for runtime agents, added AgentCore CLI commands, and restructured deployment examples
Security assessment
The changes are focused on improving documentation clarity and updating deployment procedures. There is no mention of security vulnerabilities, patches, or security incidents. The changes primarily clarify when OpenTelemetry instrumentation is required vs. automatic, update tooling from starter toolkit to AgentCore CLI, and provide better examples. No security implications are evident in the diff.
Diff
diff --git a/bedrock-agentcore/latest/devguide/observability-get-started.md b/bedrock-agentcore/latest/devguide/observability-get-started.md index b1ac46033..10e8a2279 100644 --- a//bedrock-agentcore/latest/devguide/observability-get-started.md +++ b//bedrock-agentcore/latest/devguide/observability-get-started.md @@ -38 +38 @@ Before starting, make sure you have: - * **Add the OpenTelemetry library** Include `aws-opentelemetry-distro` (ADOT) in your requirements.txt file. + * **(Non-runtime agents only) Add the OpenTelemetry library** – Include `aws-opentelemetry-distro` (ADOT) in your requirements.txt file. If you deploy using the AgentCore CLI, the runtime automatically instruments your agent and this step is not required. @@ -40 +40 @@ Before starting, make sure you have: - * Make sure that your framework is configured to emit traces (eg. `strands-agents[otel]` package), you may sometimes need to include `<your-agent-framework-auto-instrumentor>` # e.g., `opentelemetry-instrumentation-langchain` + * **(Non-runtime agents only)** Make sure that your framework is configured to emit traces (for example, `strands-agents[otel]` package). You may sometimes need to include your agent framework's auto-instrumentor (for example, `opentelemetry-instrumentation-langchain`). @@ -112 +112 @@ Let's now proceed to exploring the two ways to configure observability. -Amazon Bedrock AgentCore Runtime-hosted agents are deployed and executed directly within the Amazon Bedrock AgentCore environment, providing automatic instrumentation with minimal configuration. This approach offers the fastest path to deployment and is ideal for rapid development and testing. +Amazon Bedrock AgentCore Runtime-hosted agents are deployed and executed directly within the Amazon Bedrock AgentCore environment, providing automatic instrumentation with minimal configuration. When you deploy an agent using the AgentCore CLI, the runtime automatically instruments your agent with OpenTelemetry — no additional OTEL libraries or configuration are needed. @@ -116 +116 @@ For a complete example, refer to this [notebook](https://github.com/awslabs/amaz -### Set up folder and virtual environment +### Create your agent project @@ -118 +118 @@ For a complete example, refer to this [notebook](https://github.com/awslabs/amaz -Create a new folder for your agent. Then create and initialize a new python virtual environment. +Create a new project using the AgentCore CLI. This sets up your project folder, virtual environment, and dependencies: @@ -121,4 +121,2 @@ Create a new folder for your agent. Then create and initialize a new python virt - mkdir agentcore-observability-quickstart - cd agentcore-observability-quickstart - python3 -m venv .venv - source .venv/bin/activate + npm install -g @aws/agentcore + agentcore create --name StrandsClaudeGettingStarted @@ -126 +124 @@ Create a new folder for your agent. Then create and initialize a new python virt -### Create your agent +In the project's agent directory, replace the default agent code with your own agent logic. The following is an example using the Strands Agents SDK: @@ -128 +125,0 @@ Create a new folder for your agent. Then create and initialize a new python virt -The following is an example of using the Strands Agents SDK. @@ -130,9 +127 @@ The following is an example of using the Strands Agents SDK. -To enable OTEL exporting, install [Strands Agents](https://strandsagents.com/latest/) with otel extra dependencies: - - - pip install 'strands-agents[otel]' - -Use the following steps to host a strands agent on an AgentCore Runtime: - - - ## Save this as strands_claude.py + ## app/StrandsClaudeGettingStarted/main.py @@ -140,3 +129 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - from strands_tools import calculator # Import the calculator tool - import argparse - import json + from strands_tools import calculator @@ -148 +134,0 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - # Create a custom tool @@ -151 +137 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - """ Get weather """ # Dummy implementation + """Get weather""" @@ -154,2 +139,0 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - - model_id = "us.anthropic.claude-3-7-sonnet-20250219-v1:0" @@ -157 +141 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - model_id=model_id, + model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0", @@ -167,3 +151 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - """ - Invoke the agent with a payload - """ + """Invoke the agent with a payload""" @@ -171 +152,0 @@ Use the following steps to host a strands agent on an AgentCore Runtime: - print("User input:", user_input) @@ -178 +159 @@ Use the following steps to host a strands agent on an AgentCore Runtime: -### Deploy and invoke your agent on Amazon Bedrock AgentCore Runtime +### Deploy and invoke your agent @@ -180 +161 @@ Use the following steps to host a strands agent on an AgentCore Runtime: -Use the following code to deploy the agent to AgentCore Runtime by using the `bedrock_agentcore_starter_toolkit` package. +Deploy the agent to AgentCore Runtime. The AgentCore CLI handles packaging, deployment, and automatic OTEL instrumentation: @@ -183,4 +164,2 @@ Use the following code to deploy the agent to AgentCore Runtime by using the `be - from bedrock_agentcore_starter_toolkit import Runtime - from boto3.session import Session - boto_session = Session() - region = boto_session.region_name + cd StrandsClaudeGettingStarted + agentcore deploy @@ -188,10 +167,4 @@ Use the following code to deploy the agent to AgentCore Runtime by using the `be - agentcore_runtime = Runtime() - agent_name = "strands_claude_getting_started" - response = agentcore_runtime.configure( - entrypoint="strands_claude.py", - auto_create_execution_role=True, - auto_create_ecr=True, - requirements_file="requirements.txt", # make sure aws-opentelemetry-distro exists along with your libraries required to run your agent - region=region, - agent_name=agent_name - ) +After deployment, your agent runs on AgentCore Runtime and is automatically instrumented using OpenTelemetry. Invoke your agent and view the traces, sessions, and metrics on the GenAI Observability dashboard in Amazon CloudWatch: + + + agentcore invoke @@ -199,2 +172 @@ Use the following code to deploy the agent to AgentCore Runtime by using the `be - launch_result = agentcore_runtime.launch() - launch_result +Alternatively, you can invoke your agent programmatically using the AWS SDK: @@ -202 +173,0 @@ Use the following code to deploy the agent to AgentCore Runtime by using the `be -In these steps you deployed your strands agent to an AgentCore Runtime with the starter toolkit. When you invoke your agent, it is automatically instrumented using Open Telemetry. @@ -204 +175 @@ In these steps you deployed your strands agent to an AgentCore Runtime with the -Invoke your agent using the following command and view the Traces, sessions and metrics on GenAI Observability dashboard on Amazon CloudWatch. + import boto3, json @@ -205,0 +177,8 @@ Invoke your agent using the following command and view the Traces, sessions and + client = boto3.client('bedrock-agentcore') + + response = client.invoke_agent_runtime( + agentRuntimeArn="YOUR_AGENT_RUNTIME_ARN", + runtimeSessionId="my-observability-session-001", + payload=json.dumps({"prompt": "What is 2 + 2?"}), + qualifier="DEFAULT" + ) @@ -207,2 +186 @@ Invoke your agent using the following command and view the Traces, sessions and - invoke_response = agentcore_runtime.invoke({"prompt": "How is the weather now?"}) - invoke_response + print(json.loads(response['response'].read()))