Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Inizia con AgentCore Observability

Amazon Bedrock AgentCore Observability ti aiuta a tracciare, eseguire il debug e monitorare le prestazioni degli agenti negli ambienti di produzione. Questa guida ti aiuta a implementare le funzionalità di osservabilità nelle tue applicazioni con agenti.

Prerequisiti

Prima di iniziare, assicurati di avere:

Amazon Bedrock AgentCore Observability offre due modi per configurare il monitoraggio in base alle diverse esigenze dell'infrastruttura:

Come configurazione una tantum per AWS account, gli utenti per la prima volta devono abilitare Transaction Search su Amazon CloudWatch. Esistono due modi per farlo, tramite l'API e tramite la CloudWatch console.

Passaggio 1: abilita la ricerca delle transazioni su CloudWatch

Dopo aver abilitato Transaction Search, potrebbero essere necessari fino a dieci minuti prima che gli intervalli risultino disponibili per la ricerca e l'analisi. Scegli una delle seguenti opzioni:

Opzione 1: abilita la ricerca delle transazioni utilizzando un'API

Per abilitare la ricerca delle transazioni utilizzando l'API

Opzione 2: abilita la ricerca delle transazioni nella console CloudWatch

Per abilitare la ricerca delle transazioni nella CloudWatch console

Passiamo ora all'esplorazione dei due modi per configurare l'osservabilità.

Passaggio 2: abilitare l'osservabilità per gli agenti ospitati su Amazon Bedrock Runtime AgentCore

AgentCore Runtime-hosted Gli agenti Amazon Bedrock vengono distribuiti ed eseguiti direttamente all'interno dell' AgentCore ambiente Amazon Bedrock, fornendo strumentazione automatica con una configurazione minima. Quando si distribuisce un agente utilizzando l'interfaccia a riga di AgentCore comando, il runtime fornisce automaticamente strumenti all'agente OpenTelemetry : non sono necessarie librerie o configurazioni OTEL aggiuntive.

Per un esempio completo, consulta gli esempi di AgentCore Observability su GitHub

Crea il tuo progetto di agente

Crea un nuovo progetto usando la AgentCore CLI. Questo imposta la cartella del progetto, l'ambiente virtuale e le dipendenze:

npm install -g @aws/agentcore
agentcore create \
  --project-name StrandsObservability \
  --name StrandsClaudeGettingStarted \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none
cd StrandsObservability/app/StrandsClaudeGettingStarted
uv add strands-agents-tools
cd ../..

Nella directory degli agenti del progetto, sostituisci il codice agente predefinito con la tua logica agente. Di seguito è riportato un esempio di utilizzo dello Strands Agents SDK:

## app/StrandsClaudeGettingStarted/main.py
from strands import Agent, tool
from strands_tools import calculator
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

@tool
def weather():
    """Get weather"""
    return "sunny"

model = BedrockModel(
    model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
)
agent = Agent(
    model=model,
    tools=[calculator, weather],
    system_prompt="You're a helpful assistant. You can do simple math calculation, and tell the weather."
)

@app.entrypoint
def strands_agent_bedrock(payload):
    """Invoke the agent with a payload"""
    user_input = payload.get("prompt")
    if not isinstance(user_input, str) or not user_input:
        return "Error: 'prompt' must be a non-empty string"
    response = agent(user_input)
    return response.message['content'][0]['text']

if __name__ == "__main__":
    app.run()

Implementa e richiama il tuo agente

Distribuisci l'agente su Runtime. AgentCore La AgentCore CLI gestisce il packaging, l'implementazione e la strumentazione OTEL automatica:

agentcore deploy

Dopo la distribuzione, l'agente viene eseguito su AgentCore Runtime e viene automaticamente strumentato utilizzando. OpenTelemetry Richiama il tuo agente e visualizza le tracce, le sessioni e le metriche sulla dashboard GenAI Observability in Amazon: CloudWatch

agentcore invoke

In alternativa, puoi richiamare il tuo agente in modo programmatico utilizzando l'SDK: AWS

import boto3, json

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"
)

print(json.loads(response['response'].read()))

Passaggio 3: abilitare l'osservabilità per gli agenti non Amazon Bedrock AgentCore-hosted

Agli agenti che operano al di fuori del AgentCore runtime di Amazon Bedrock, puoi fornire le stesse funzionalità di monitoraggio per gli agenti distribuiti sulla tua infrastruttura. Ciò consente un'osservabilità costante indipendentemente da dove si trovano gli agenti. Utilizzate i passaggi seguenti per configurare le variabili di ambiente necessarie per osservare i vostri agenti.

Per un esempio completo, consulta l'esempio Agents on Amazon EKS sul GitHub sito Web.

Configura AWS variabili di ambiente

export AWS_ACCOUNT_ID=<account id>
export AWS_DEFAULT_REGION=<default region>
export AWS_REGION=<region>
export AWS_ACCESS_KEY_ID=<access key id>
export AWS_SECRET_ACCESS_KEY=<secret key>

Configurare la CloudWatch registrazione

Crea un gruppo di log e un flusso di log per il tuo agente in Amazon CloudWatch che puoi utilizzare per configurare le seguenti variabili di ambiente.

Configura le variabili di OpenTelemetry ambiente

export AGENT_OBSERVABILITY_ENABLED=true # Activates the ADOT pipeline
export OTEL_PYTHON_DISTRO=aws_distro # Uses AWS Distro for OpenTelemetry
export OTEL_PYTHON_CONFIGURATOR=aws_configurator # Sets AWS configurator for ADOT SDK
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # Configures export protocol
export  OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-LOG-STREAM>,x-aws-metric-namespace=<YOUR-NAMESPACE>
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-TRACES-LOG-STREAM>
# (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR-AGENT-NAME> # Identifies your agent in observability data
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
export OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
export OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

Sostituiscilo <YOUR-AGENT-NAME> con un nome univoco per identificare questo agente nella dashboard e nei log di GenAI Observability.

Crea un agente localmente

# Create agent.py -  Strands agent that is a weather assistant
from strands import Agent
from strands_tools import http_request

# Define a weather-focused system prompt
WEATHER_SYSTEM_PROMPT = """You are a weather assistant with HTTP capabilities. You can:

1. Make HTTP requests to the National Weather Service API
2. Process and display weather forecast data
3. Provide weather information for locations in the United States

When retrieving weather information:
1. First get the coordinates or grid information using https://api.weather.gov/points/{latitude},{longitude} or https://api.weather.gov/points/{zipcode}
2. Then use the returned forecast URL to get the actual forecast

When displaying responses:
- Format weather data in a human-readable way
- Highlight important information like temperature, precipitation, and alerts
- Handle errors appropriately
- Convert technical terms to user-friendly language

Always explain the weather conditions clearly and provide context for the forecast.
"""

# Create an agent with HTTP capabilities
weather_agent = Agent(
    system_prompt=WEATHER_SYSTEM_PROMPT,
    tools=[http_request],  # Explicitly enable http_request tool
)

response = weather_agent("What's the weather like in Seattle?")
print(response)

Esegui il tuo agente con un comando di strumentazione automatico

aws-opentelemetry-distroNel tuo requirements.txt, il opentelemetry-instrument comando:

Usa il seguente comando per eseguire il tuo agente con la strumentazione automatica:

opentelemetry-instrument python agent.py

Se ospiti il tuo agente su AWS Lambda, utilizza Lambda AWS Layer for OpenTelemetry sul sito web di Distro for. AWS OpenTelemetry Aggiungi il livello alla tua funzione, quindi imposta la variabile di AWS_LAMBDA_EXEC_WRAPPER ambiente su. /opt/otel-instrument Il livello quindi strumenta automaticamente la tua funzione. Con questo approccio, non è necessario aggiungere il aws-opentelemetry-distro pacchetto o eseguire il opentelemetry-instrument comando descritto in precedenza.

Ora puoi visualizzare le tue tracce, sessioni e metriche su GenAI Observability Dashboard su Amazon CloudWatch con il valore che hai configurato nelle variabili di ambiente. YOUR-AGENT-NAME Configura le variabili di OpenTelemetry ambiente

Per correlare le tracce tra le esecuzioni di più agenti, puoi associare un ID di sessione ai tuoi dati di telemetria utilizzando baggage: OpenTelemetry

from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)

Fase 4: Osserva il tuo agente con GenAI Observability su Amazon CloudWatch

Dopo aver implementato l'osservabilità, puoi visualizzare i dati raccolti in: CloudWatch

Osserva il tuo agente

Visualizza gli accessi CloudWatch

Per visualizzare i log in CloudWatch

Visualizza tracce e intervalli

Per visualizzare tracce e intervalli

Visualizzazione dei parametri di

Per visualizzare le metriche

Best practice