View a markdown version of this page

Introducción - Amazon Bedrock AgentCore
Requisitos previosIntroducciónDocumentación de la APIFormato de respuesta de streaming

Introducción

Puede utilizar el arnés a través de la AgentCore CLI o directamente con AWS SDK comoboto3. La CLI es la ruta más rápida para la mayoría de los desarrolladores; los SDK son para uso programático desde su propia aplicación.

Requisitos previos

Introducción

ejemplo
AWS CLI/boto3

Cree el arnés con un nombre y un rol de ejecución:

aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"

Encuesta get-harness hasta"status": "READY". Tenga en cuenta los arn en la respuesta.

aws bedrock-agentcore-control get-harness \
  --harness-id "MyHarness-XyZ123"

Invoca desde Python. Si no especificas un modelo, el arnés toma el Anthropic Claude Sonnet 4.6 por defecto en Amazon Bedrock:

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = client.invoke_harness(
    harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123",  # Replace with your harness ARN
    runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",
    messages=[{
        "role": "user",
        "content": [{"text": "Research three tropical vacation options under $3k."}]
    }],
)

for event in response["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"].get("delta", {})
        if "text" in delta:
            print(delta["text"], end="", flush=True)
    elif "runtimeClientError" in event:
        print(f"\nError: {event['runtimeClientError']['message']}")
AgentCore CLI

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Cree un proyecto de arnés de forma no interactiva con indicadores:

agentcore create --name myresearchagent --model-provider bedrock

Despliegue e invoque:

agentcore deploy
agentcore invoke --harness myresearchagent \
  --session-id "$(uuidgen)" \
  "Research three tropical vacation options under $3k, within five hours of NYC."

La respuesta se transmite a su terminal. Reutilice lo mismo --session-id en todas las invocaciones para continuar la conversación en el mismo entorno.

Para añadir más arneses a un proyecto existente, utilice. agentcore add harness Para generar un script de invocación de Python independiente, añada. --with-invoke-script

Banderas útiles:

  • --no-browser(-b): usa la TUI del terminal en lugar del inspector del navegador

  • --logs(-l): se ejecuta en modo no interactivo con registros en modo stdout

  • --port <port>(-p): configura el puerto del servidor de desarrollo (predeterminado 8080)

  • --no-traces- deshabilitar la recopilación local de rastreos de OTEL

Interactive

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Ejecute agentcore create sin indicadores para iniciar el asistente interactivo:

agentcore create

  1. Introduzca el nombre de su proyecto:

    Asistente de creación: introduzca el nombre del proyecto

  2. Seleccione Harness como tipo de proyecto:

    Asistente de creación: seleccione el tipo de proyecto

  3. Elija su proveedor de modelos:

    Asistente de creación: seleccione el proveedor de modelos

  4. Elija su entorno (predeterminado, URI del contenedor o Dockerfile):

    Asistente de creación: seleccione el entorno

  5. Configurar la memoria:

    Asistente de creación: configurar la memoria

  6. Si lo desea, configure los ajustes avanzados (herramientas, autenticación, red, ciclo de vida, límites, truncamiento, almacenamiento de sesiones):

    Asistente de creación: configuración avanzada

  7. Revise la configuración y confirme:

    Asistente de creación: revise y confirme

Tras la confirmación, el asistente organiza el proyecto. Implemente con yagentcore deploy, a continuación, invoque con. agentcore invoke

Compruebe el estado del proyecto en cualquier momento conagentcore status:

AgentCore panel de estado

  1. Desarrollo local

Si desea probar el arnés en su entorno local, puede ejecutar el servidor de desarrollo:

agentcore dev

Cuando lo ejecutasagentcore dev, la CLI primero despliega tus recursos de arnés y crea el rol de IAM, el arnés y cualquier memoria o credencial configurada en tu proyecto: AWS

Progreso de la implementación: CloudFormation creación de recursos

Una vez completada la implementación, se inicia un servidor local y se abre el inspector de agentes en el navegador, donde puede charlar con el arnés, inspeccionar las huellas y buscar los recursos del proyecto:

Agente inspector: chatea con tu arnés

Amplíe la configuración del arnés para ver y anular la configuración del arnés de la sesión actual:

Inspector de agentes: ajustes y configuración del arnés

Eso es todo lo que necesita para poner en marcha un arnés. En las siguientes secciones se describe todo lo que puede configurar.

nota

runtimeSessionIdDebe tener al menos 33 caracteres. Utilice un UUID o un identificador similar. Reutilice el mismo ID de sesión en todas las invocaciones para continuar una conversación en el mismo entorno.

Documentación de la API

Para obtener más información, consulta la referencia de la API:

Formato de respuesta de streaming

InvokeHarnessdevuelve una secuencia de eventos. Los tipos de eventos clave son:

  • messageStart- comienzo de un mensaje nuevo (incluyerole)

  • contentBlockStart- principio de un bloque de contenido (textotoolUse, otoolResult)

  • contentBlockDelta- contenido incremental (text, toolUse entrada,reasoningContent)

  • contentBlockStop- final de un bloque de contenido

  • messageStop- final del mensaje (incluyestopReason)

  • metadata- métricas de uso y latencia de los tokens

  • runtimeClientError- error durante la ejecución

El stopReason in messageStop indica el motivo por el que el agente se detuvo:

  • end_turn- el agente terminó con normalidad

  • tool_use- el agente está llamando a una función en línea y esperando el resultado del lado del cliente

  • max_tokens- se ha alcanzado el límite de fichas por turno del modelo

  • max_iterations_exceeded- se alcanzó el maxIterations límite

  • timeout_exceeded- se alcanzó el timeoutSeconds límite

  • max_output_tokens_exceeded- el maxTokens presupuesto estaba agotado