View a markdown version of this page

Introducción - Base amazónica AgentCore
Requisitos previosIntroducciónDocumentación de la APIFormato de respuesta en streaming

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Introducción

Puede usar 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

  • AWS credenciales configuradas en una de las regiones compatibles.

  • Para la CLI: más de Node.js 20

  • Para Python 3.10+, boto3 instalado, y una función de ejecución de IAM que el arnés pueda asumir. SDK/boto3 Consulta la política de funciones de ejecución para conocer los permisos mínimos.

Introducción

ejemplo
AWS CLI/boto3

Cree el arnés con un nombre y una función 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 especifica ningún modelo, el arnés se establece de forma predeterminada en Anthropic Claude Sonnet 4.6 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 CLI: AgentCore 

npm install -g @aws/agentcore

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

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

Implemente 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. Reutiliza 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 los registros en la salida estándar

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

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

Interactive

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Ejecute agentcore create sin marcas para iniciar el asistente interactivo:

agentcore create

  1. Introduzca el nombre de su proyecto:

    Asistente de creación: introduce el nombre del proyecto

  2. Seleccione Harness como tipo de proyecto:

    Asistente de creación: seleccione el tipo de proyecto

  3. Elige tu proveedor de modelos:

    Asistente de creación: seleccione el proveedor del modelo

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

    Asistente de creación: seleccione el entorno

  5. Configure la memoria:

    Asistente de creación: configurar la memoria

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

    Asistente de creación: configuración avanzada

  7. Revisa tu configuración y confirma:

    Asistente de creación: revise y confirme

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

Comprueba el estado del proyecto en cualquier momento conagentcore status:

AgentCore panel de estado

  1. Desarrollo local

Si quieres probar el arnés en tu entorno local, puedes ejecutar el servidor de desarrollo:

agentcore dev

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

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

Una vez finalizada la implementación, se inicia un servidor local y se abre el inspector de agentes en su navegador, donde puede chatear con el arnés, inspeccionar los rastros y explorar 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 necesitas para poner en marcha un arnés. Las siguientes secciones cubren todo lo que puede configurar.

nota

runtimeSessionIdDebe tener al menos 33 caracteres. Usa un UUID o un identificador similar. Reutiliza 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 en streaming

InvokeHarnessdevuelve un flujo de eventos. Los tipos de eventos clave son:

  • messageStart- comienzo de un mensaje nuevo (incluyerole)

  • contentBlockStart- principio de un bloque de contenido (texto otoolResult) toolUse

  • contentBlockDelta- contenido incremental (text, toolUse entradareasoningContent)

  • contentBlockStop- fin de un bloque de contenido

  • messageStop- fin del mensaje (incluyestopReason)

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

  • runtimeClientError- error durante la ejecución

La stopReason entrada messageStop indica por qué se detuvo el agente:

  • end_turn- el agente terminó con normalidad

  • tool_use- el agente llama a una función en línea y espera un resultado del lado del cliente

  • max_tokens- se alcanzó el límite de fichas por turno del modelo

  • max_iterations_exceeded- se alcanzó maxIterations el límite

  • timeout_exceeded- se alcanzó el timeoutSeconds límite

  • max_output_tokens_exceeded- se agotó el maxTokens presupuesto