View a markdown version of this page

Conceitos básicos - Base da Amazônia AgentCore
Pré-requisitosConceitos básicosDocumentação de APIFormato de resposta de streaming

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Conceitos básicos

Você pode usar o equipamento por meio da AgentCore CLI ou diretamente com AWS SDKs, como. boto3 A CLI é o caminho mais rápido para a maioria dos desenvolvedores; os SDKs são para uso programático a partir de seu próprio aplicativo.

Pré-requisitos

Conceitos básicos

exemplo
AWS CLI/boto3

Crie o equipamento com um nome e uma função de execução:

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

Faça uma enquete get-harness até"status": "READY". Observe o arn na resposta.

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

Invoque a partir do Python. Se você não especificar um modelo, o padrão do chicote é Anthropic Claude Sonnet 4.6 no 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 a AgentCore CLI:

npm install -g @aws/agentcore

Crie um projeto de aproveitamento de forma não interativa com sinalizadores:

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

Implante e invoque:

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

A resposta é transmitida para o seu terminal. Reutilize o mesmo --session-id em todas as invocações para continuar a conversa no mesmo ambiente.

Para adicionar mais equipamentos a um projeto existente, useagentcore add harness. Para gerar um script de invocação independente do Python, adicione. --with-invoke-script

Bandeiras úteis:

  • --no-browser(-b) - use o terminal TUI em vez do inspetor do navegador

  • --logs(-l) - executado no modo não interativo com registros em stdout

  • --port <port>(-p) - defina a porta do servidor de desenvolvimento (padrão 8080)

  • --no-traces- desativar a coleta de rastreamento OTEL local

Interactive

Instale a AgentCore CLI:

npm install -g @aws/agentcore

Execute agentcore create sem sinalizadores para iniciar o assistente interativo:

agentcore create

  1. Insira o nome do seu projeto:

    Assistente de criação: insira o nome do projeto

  2. Selecione Harness como o tipo de projeto:

    Assistente de criação: selecione o tipo de projeto

  3. Escolha seu fornecedor de modelos:

    Assistente de criação: selecione o fornecedor do modelo

  4. Escolha seu ambiente (padrão, URI do contêiner ou Dockerfile):

    Assistente de criação: selecione o ambiente

  5. Configure a memória:

    Assistente de criação: configure a memória

  6. Opcionalmente, defina configurações avançadas (ferramentas, autenticação, rede, ciclo de vida, limites, truncamento, armazenamento de sessão):

    Assistente de criação: configurações avançadas

  7. Revise sua configuração e confirme:

    Assistente de criação: revise e confirme

Após a confirmação, o assistente organiza seu projeto. Implante com agentcore deploy e, em seguida, invoque comagentcore invoke.

Verifique o status do projeto a qualquer momento comagentcore status:

AgentCore painel de status

  1. Desenvolvimento local

Se quiser testar o equipamento em seu ambiente local, você pode executar o servidor de desenvolvimento:

agentcore dev

Quando você executaagentcore dev, a CLI primeiro implanta seus recursos de aproveitamento em AWS, criando a função do IAM, o aproveitamento e qualquer memória ou credenciais configuradas em seu projeto:

Progresso da implantação: criação CloudFormation de recursos

Quando a implantação é concluída, ele inicia um servidor local e abre o inspetor de agentes em seu navegador, onde você pode conversar com o equipamento, inspecionar rastreamentos e navegar pelos recursos do projeto:

Agente inspetor: converse com seu equipamento

Expanda Configurações do chicote para visualizar e substituir a configuração do chicote da sessão atual:

Inspetor de agentes: configurações e configurações do chicote

Isso é tudo que você precisa para colocar um cinto em funcionamento. As seções a seguir abrangem tudo o que você pode configurar.

nota

runtimeSessionIdDeve ter pelo menos 33 caracteres. Use um UUID ou identificador similar. Reutilize o mesmo ID de sessão em todas as invocações para continuar uma conversa no mesmo ambiente.

Documentação de API

Para obter mais detalhes, consulte a Referência da API:

Formato de resposta de streaming

InvokeHarnessretorna um fluxo de eventos. Os principais tipos de eventos são:

  • messageStart- início de uma nova mensagem (incluirole)

  • contentBlockStart- início de um bloco de conteúdo (textotoolUse, outoolResult)

  • contentBlockDelta- conteúdo incremental (text, toolUse entrada,reasoningContent)

  • contentBlockStop- fim de um bloco de conteúdo

  • messageStop- fim da mensagem (incluistopReason)

  • metadata- métricas de uso e latência de tokens

  • runtimeClientError- erro durante a execução

A stopReason entrada messageStop indica por que o agente parou:

  • end_turn- o agente terminou normalmente

  • tool_use- o agente está chamando uma função embutida e aguardando um resultado do lado do cliente

  • max_tokens- o limite de fichas por turno do modelo foi atingido

  • max_iterations_exceeded- o maxIterations limite foi atingido

  • timeout_exceeded- o timeoutSeconds limite foi atingido

  • max_output_tokens_exceeded- o maxTokens orçamento estava esgotado