View a markdown version of this page

Recomendações - Base da Amazônia AgentCore
Modos de entrada de configuraçãoFontes de rastreamento de agentes

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á.

Recomendações

As recomendações usam a IA para gerar configurações otimizadas de agentes a partir de rastreamentos reais de sessões. Em vez de reescrever manualmente as solicitações ou as descrições das ferramentas, você aponta o serviço para os rastros do seu agente, especifica um avaliador-alvo como sinal de recompensa e recebe uma configuração otimizada.

nota

As recomendações são geradas pelos LLMs. Revise e teste antes de aplicá-los.

O Amazon Bedrock AgentCore oferece suporte a dois tipos de recomendação:

  • Recomendação de solicitação do sistema: analisa os rastros do agente e gera uma solicitação otimizada do sistema que melhora o desempenho do avaliador alvo. O serviço identifica padrões de falha e adiciona instruções comportamentais específicas.

  • Recomendação de descrição da ferramenta: analisa os traços do agente e gera descrições de ferramentas aprimoradas que reduzem a confusão na seleção de ferramentas. Isso é útil quando os agentes selecionam a ferramenta errada para solicitações ambíguas.

Cada recomendação exige duas entradas: a configuração atual do agente para otimizar e os rastreamentos do agente para analisar.

Tópicos

Modos de entrada de configuração

Você fornece a configuração atual de uma das duas maneiras:

  • Texto embutido: forneça a configuração diretamente como uma string na solicitação da API. Para recomendações de solicitação do sistema, passe o texto da solicitação no systemPrompt.text campo. Para recomendações de descrição da ferramenta, passe o nome e a descrição de cada ferramenta na toolDescription.toolDescriptionText.tools lista. Esse modo é útil para experiências rápidas, quando você deseja testar um prompt no qual está iterando ativamente ou quando sua configuração não está armazenada em um pacote.

    Tipo de recomendação Sinalizadores CLI Campo da API

    Prompt do sistema

    --inline "prompt text" ou --prompt-file ./path.txt

    systemPrompt.text

    Descrição da ferramenta

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: lista de objetos com toolName e toolDescription

  • Pacote de configuração: faça referência a uma versão existente do pacote de configuração. O serviço lê a configuração atual do pacote usando o caminho JSON que você especifica, gera a versão otimizada e grava o resultado em uma nova versão do pacote. Isso mantém seu histórico de otimização controlado junto com seu pacote. Esse modo é útil quando você gerencia configurações centralmente com pacotes de configuração e deseja que a saída otimizada seja gravada automaticamente no pacote.

    Tipo de recomendação Sinalizadores CLI Campo da API

    Prompt do sistema

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundlecombundleArn,versionId, systemPromptJsonPath

    Descrição da ferramenta

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (repita para cada ferramenta)

    toolDescription.configurationBundlecombundleArn,versionId, e tools lista contendo toolName e toolDescriptionJsonPath

    Ao usar um pacote de configuração, o resultado da recomendação inclui um configurationBundle campo com o bundleArn e um novo versionId apontando para a versão do pacote que contém a configuração otimizada.

Fontes de rastreamento de agentes

O agentTraces parâmetro aceita uma das quatro fontes:

  • CloudWatch Registros: use quando o tempo de execução do seu agente grava telemetria em. CloudWatch O serviço lê rastreamentos diretamente dos grupos de registros especificados dentro de um intervalo de tempo necessário. Você deve fornecer logGroupArns serviceNamesstartTime,, endTime e. Um rule campo opcional permite filtrar rastreamentos (por exemplo, selecionar somente sessões que goal_success_rate estejam abaixo de um limite).

    nota

    A API de recomendações usa ARNs de grupos de registros (logGroupArns), não nomes de grupos de registros. Isso difere das avaliações em lote, que usamlogGroupNames.

    Campo Tipo Obrigatório Description

    cloudwatchLogs.logGroupArns

    Lista de strings

    Sim

    CloudWatch Registra os ARNs do grupo de registros em que a telemetria do agente é armazenada. Formato: arn:aws:logs:{region}:{account}:log-group:{log-group-name}.

    cloudwatchLogs.serviceNames

    Lista de strings

    Sim

    Nomes de serviços que identificam os rastros de seu agente CloudWatch. Convenção:{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    Data e hora ISO 8601

    Sim

    Início da janela de coleta de traços. Somente traços após esse período são incluídos.

    cloudwatchLogs.endTime

    Data e hora ISO 8601

    Sim

    Fim da janela de coleta de traços. Somente traços anteriores a esse período são incluídos.

    cloudwatchLogs.rule

    Objeto

    Não

    Regra de filtro opcional para restringir a seleção de traços. Contém uma filters lista em que cada filtro especifica umkey, operator (comoLESS_THAN) e value (como{"doubleValue": 0.5}).
    exemplo
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    Com um filtro de regras opcional para selecionar somente sessões de baixo desempenho:

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • Expansões de sessão em linha: use quando você tiver rastreamentos disponíveis localmente (por exemplo, de uma execução de teste local, de um CI/CD pipeline ou de uma sessão específica que você deseja otimizar). Você fornece as extensões diretamente no corpo da solicitação da API como uma lista de objetos de OpenTelemetry-compatible extensão.

    Campo Tipo Obrigatório Description

    sessionSpans

    Lista de objetos

    Sim

    O rastreamento do agente abrange o OpenTelemetry-compatible formato. Cada intervalo inclui ID de rastreamento, ID de intervalo, nome, carimbos de data/hora e atributos.
    exemplo
    AgentCore CLI

    Abrange o arquivo (lê extensões de um arquivo JSON local e as passa como extensões embutidas):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --spans-file agent-traces.json

    IDs de sessão específicos (a CLI coleta extensões do lado do cliente e as transmite como extensões embutidas):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

with open("agent-traces.json") as f:
    spans = json.load(f)

agent_traces = {
    "sessionSpans": spans
}
nota

A avaliação em lote e as fontes de rastreamento de avaliação on-line estão disponíveis somente para recomendações rápidas do sistema.

  • Avaliação em lote: use quando você tiver um trabalho de avaliação em lote concluído cujas sessões você deseja reutilizar para otimização. Em vez de coletar novamente traços CloudWatch ou fornecer extensões em linha, você faz referência à avaliação do lote diretamente por seu ARN. Essa fonte está disponível somente para recomendações de solicitações do sistema.

    • Se os avaliadores usados no trabalho de avaliação em lote corresponderem aos avaliadores especificados na solicitação de recomendação, o serviço reutilizará as pontuações existentes.

    • Se os avaliadores não corresponderem, o serviço executará novas avaliações para os avaliadores solicitados em relação às sessões de avaliação em lote.

      Campo Tipo Obrigatório Descrição

      batchEvaluation.batchEvaluationArn

      String

      Sim

      ARN de um trabalho de avaliação em lote concluído. O serviço reutiliza as sessões desse trabalho como entrada de rastreamento. Formato: arn:aws:bedrock-agentcore:{region}:{account}:batch-evaluation/{id}.
      exemplo
      AWS SDK (boto3)
      agent_traces = {
    "batchEvaluation": {
        "batchEvaluationArn": "<batch-evaluation-arn>"
    }
}

  • Avaliação on-line: use quando você tiver uma configuração de avaliação on-line que avalia continuamente as sessões do agente ao vivo. Como a avaliação on-line é um fluxo contínuo, você deve especificar uma janela de tempo (startTimeeendTime) para limitar as sessões avaliadas das quais a recomendação se baseia. O serviço reutiliza as pontuações de avaliação das sessões de avaliação on-line dentro da janela especificada. Essa fonte está disponível somente para recomendações de solicitações do sistema.

    Campo Tipo Obrigatório Descrição

    onlineEvaluation.onlineEvaluationConfigArn

    String

    Sim

    ARN de uma configuração de avaliação on-line. O serviço usa as sessões avaliadas dessa configuração como entrada de rastreamento. Formato: arn:aws:bedrock-agentcore:{region}:{account}:online-evaluation-config/{id}.

    onlineEvaluation.startTime

    Data e hora ISO 8601

    Sim

    Início da janela de avaliação. Somente as sessões avaliadas após esse período são incluídas.

    onlineEvaluation.endTime

    Data e hora ISO 8601

    Sim

    Fim da janela de avaliação. Somente as sessões avaliadas antes desse horário são incluídas.
    exemplo
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "onlineEvaluation": {
        "onlineEvaluationConfigArn": "<online-evaluation-config-arn>",
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}
nota

agentcore run recommendationé assíncrono. Sem --wait isso, o comando envia o trabalho de recomendação e retorna imediatamente; o trabalho começa em um estado não terminal (como PENDING ouIN_PROGRESS) e você recupera o resultado posteriormente. Passe --wait para o bloco até que a recomendação atinja um estado terminal. Para pesquisar ou recuperar o resultado de um trabalho enviado, executeagentcore view recommendation <id>, onde id está o ID do trabalho recomendado.

A AgentCore CLI fornece sinalizadores de conveniência que mapeiam os tipos de origem de rastreamento da API subjacente:

Bandeira CLI Mapeamento de API Description

--lookback <days>

cloudwatchLogscom computado e startTime endTime

Coleta traços dos últimos N dias por meio de CloudWatch registros. A CLI resolve ARNs de grupos de log e nomes de serviços da configuração de tempo de execução.

--session-id <id>

sessionSpans(em linha)

Coleta períodos para a sessão especificada do lado do cliente e os transmite como períodos de sessão embutidos. A API de recomendação em si não oferece suporte à filtragem de ID de sessão nas CloudWatch fontes.

--spans-file <path>

sessionSpans(em linha)

Lê os intervalos de um arquivo JSON local e os passa como períodos de sessão embutidos.

--wait

n/a (pesquisa do lado do cliente)

Bloqueie até que a recomendação atinja um estado terminal.