View a markdown version of this page

Recomendações - Amazon Bedrock AgentCore
Modos de entrada de configuraçãoFontes de rastreamento do agente

Recomendações

As recomendações usam a IA para gerar configurações otimizadas de agentes a partir de rastreamentos de sessão reais. Em vez de reescrever manualmente as instruçõ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á-las.

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

  • Recomendação imediata do sistema: analisa os rastreamentos 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 mais precisas 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 requer 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 duas maneiras:

  • Texto embutido: forneça a configuração diretamente como uma string na solicitação da API. Para recomendações de solicitações do sistema, passe o texto da solicitação no systemPrompt.text campo. Para recomendações de descrição de ferramentas, passe o nome e a descrição de cada ferramenta na toolDescription.toolDescriptionText.tools lista. Esse modo é útil para experimentação rápida, 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 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 atualizado 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 de volta no pacote automaticamente.

    Tipo de recomendação Sinalizadores CLI Campo 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 do agente

O agentTraces parâmetro aceita uma das duas fontes:

  • CloudWatch Registros: use quando o tempo de execução do agente grava telemetria em. CloudWatch O serviço lê os 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 goal_success_rate abaixo de um limite).

    nota

    A API de recomendações usa ARNs (logGroupArns) de grupos de registros, 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/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/hora ISO 8601

    Sim

    Fim da janela de coleta de traços. Somente traços anteriores a esse horário 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 com a qual 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

    Arquivo de extensões (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 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..." \
  --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

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 bloquear 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 subjacentes:

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 registros e nomes de serviços a partir 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 passa como períodos de sessão em linha. 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ê extensões de um arquivo JSON local e as passa como extensões de sessão embutidas.

--wait

n/a (pesquisa do lado do cliente)

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