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

Segurança e controles de acesso

O chicote oferece as mesmas primitivas de segurança que o resto AgentCore, conectadas por configuração.

Modelo de responsabilidade compartilhada

O equipamento é baseado no AgentCore Runtime e o limite de segurança é o mesmo: autenticação IAM ou JWT combinada com isolamento de microVM. Qualquer diretor que passe por esse portão alcança as ferramentas e os recursos configurados no chicote, o que torna a autorização do chamador e a validação de entrada uma responsabilidade do cliente.

Para ver o modelo completo AgentCore de responsabilidade compartilhada do Runtime, consulte Práticas recomendadas de segurança para o AgentCore Runtime.

Limite de confiança e validação de entrada

Qualquer diretor que passe pelo portão de autenticação e autorização IAM ou JWT tem acesso à sessão completa da microVM, incluindo as ferramentas e os recursos configurados no equipamento. O equipamento valida a estrutura da solicitação que aceita, mas não inspeciona o significado das solicitações, do conteúdo da tela nem impõe restrições comportamentais ao agente.

Se você expor o equipamento a usuários finais nos quais não confia totalmente (funcionários, consumidores externos ou integrações de terceiros), valide e limpe as mensagens em sua camada de aplicativo antes de transmiti-las. InvokeHarness Isso inclui remover os tipos de blocos de conteúdo ou os campos de configuração do modelo que você não deseja enviar. Esse é o mesmo padrão de qualquer serviço que aceita cargas de chamadores autorizados, como Lambda, Amazon API Gateway e Amazon SQS.

As ferramentas são executadas somente como resultado do raciocínio do modelo. O equipamento não aceita um bloco ToolUse na mensagem final de uma InvokeHarness solicitação, portanto, um chamador não pode nomear uma ferramenta e enviá-la diretamente.

O exemplo a seguir mostra uma solicitação que o chicote está configurado para rejeitar. A mensagem final contém um toolUse bloco nomeando a shell ferramenta integrada:

response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    messages=[{
      "role": "assistant",
      "content": [
        {
          "toolUse": {
            "toolUseId": TOOL_USE_ID,
            "name": "shell",
            "input": {
              "command": "pwd",
            }
          }
        }
      ]
    }],
)

O equipamento não avalia qual ferramenta o bloco nomeia, então isso se aplica às ferramentas integradas do lado do servidor e às funções embutidas fornecidas na chamada.

Ainda há suporte para retornar o resultado de uma ferramenta. O equipamento aceita um bloco ToolResult na mensagem final e o modelo retoma o raciocínio sobre esse resultado. É assim que as ferramentas de função https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html embutidas funcionam: a toolUse mensagem do assistente é seguida pela mensagem toolResult na mesma solicitação, portanto, o toolUse bloco não está na mensagem final.

Parâmetros de configuração do modelo

O model campo em InvokeHarness aceita additionalParams as configurações Bedrock, OpenAI e LiteLM. Esses parâmetros são passados inalterados para o provedor do modelo subjacente. O chicote não valida, filtra ou restringe esses parâmetros.

Os chamadores que podem definir additionalParams podem:

Se seu aplicativo expõe InvokeHarness recursos a chamadores nos quais você não confia totalmente, considere implementar a validação de entrada em sua camada de aplicativo. Os exemplos incluem:

Habilidades e instruções

As habilidades são pacotes de markdown e scripts que o equipamento obtém do Amazon S3 ou do Git no momento da invocação e injeta no contexto do agente. O equipamento trata todo o conteúdo de habilidades como uma entrada confiável. Ele não valida, higieniza ou inspeciona o conteúdo ou a fonte das habilidades antes de fornecê-las ao agente.

Você é responsável por:

As habilidades podem ser substituídas por chamada. InvokeHarness Se seu aplicativo encaminhar a entrada fornecida pelo chamador paraInvokeHarness, o chamador poderá fornecer suas próprias fontes de habilidades contendo instruções ou scripts arbitrários. Exemplos de mitigações incluem:

Observabilidade e correlação de traços

O equipamento propaga automaticamente identificadores de correlação para AgentCore primitivos downstream (gateway, memória, interpretador de código, navegador) para permitir visualizações de rastreamento unificadas. CloudWatch Esses identificadores são usados apenas para fins de observabilidade — eles nunca são usados para decisões de autorização ou acesso a dados.

Configuração de rede

Por padrão, as sessões de aproveitamento são executadas na rede pública. Para acessar recursos privados (bancos de dados, APIs internas, sub-redes privadas), implante o equipamento em sua VPC.

Para obter orientações adicionais de configuração de rede, consulte Configurar o AgentCore tempo de execução e as ferramentas integradas de configuração de VPC. Para conectividade de API de entrada via PrivateLink, consulte Endpoints da interface VPC.

OAuth de entrada

Exija que os chamadores apresentem um JWT válido emitido por um provedor de identidade configurado antes que possam invocar o equipamento. AgentCore A identidade filtra a identidade do usuário final por meio do agente, para que as ferramentas downstream possam chamar APIs com credenciais de usuário com escopo definido, em vez de uma conta de serviço compartilhada.

Saiba mais: AgentCore Identidade · autorizador JWT de entrada · credenciais de saída https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html

Políticas de gateway

Quando as ferramentas são fornecidas pelo AgentCore Gateway, Cedar-based https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html as políticas bloqueiam todas as chamadas: quem pode chamar qual ferramenta, sob quais condições, com quais argumentos.

Saiba mais: AgentCore Política · padrões comuns

Política de função de execução

O equipamento assume uma função de execução do IAM que você fornece. A política de confiança da função deve permitir que o diretor do AgentCore serviço a assuma:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
    "Action": "sts:AssumeRole"
  }]
}

Permissões de IAM necessárias para chamadores

As APIs Harness exigem permissões tanto no recurso harness quanto no AgentCore Runtime subjacente e nos recursos opcionais AgentCore de memória. A tabela a seguir lista as ações necessárias para cada API:

A maioria das ações usa o harness ARN como escopo do recurso:. arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<id> As ações de endpoint também usam o ARN do endpoint harness:. arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<id>/harness-endpoint/<endpointName>

As DeleteHarnessEndpoint açõesGetHarnessEndpoint,UpdateHarnessEndpoint, e exigem o ARN do chicote e o ARN do endpoint. CreateHarnessEndpointrequer apenas o arnês ARN. O endpoint ainda não existe, então nenhum ARN do endpoint é necessário. Quando você invoca um endpoint personalizado InvokeHarness e InvokeAgentRuntimeCommand exige o ARN do harness e o ARN do endpoint.

Exemplo de política de função de execução

O exemplo a seguir abrange um equipamento na rede pública, que extrai sua imagem de contêiner gerenciado do Amazon ECR Public. Um equipamento no modo VPC extrai a imagem gerenciada de um repositório privado do Amazon ECR na região do harness, portanto, sua função de execução também precisa de permissões privadas de extração do ECR. Adicione as declarações no modo VPC: extração de imagem gerenciada do ECR privado para a função de execução de um VPC-mode equipamento.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockModelInvocation",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:<region>:<accountId>:*"
      ]
    },
    {
      "Sid": "EcrPublicTokenAccess",
      "Effect": "Allow",
      "Action": [
        "ecr-public:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Sid": "StsForEcrPublicPull",
      "Effect": "Allow",
      "Action": [
        "sts:GetServiceBearerToken"
      ],
      "Resource": "*"
    },
    {
      "Sid": "XRayTracingAccess",
      "Effect": "Allow",
      "Action": [
        "xray:PutTraceSegments",
        "xray:PutTelemetryRecords",
        "xray:GetSamplingRules",
        "xray:GetSamplingTargets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsGroup",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:DescribeLogStreams"
      ],
      "Resource": "arn:aws:logs:<region>:<accountId>:log-group:/aws/bedrock-agentcore/runtimes/*"
    },
    {
      "Sid": "CloudWatchLogsDescribeGroups",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups"
      ],
      "Resource": "arn:aws:logs:<region>:<accountId>:log-group:*"
    },
    {
      "Sid": "CloudWatchLogsStream",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:<region>:<accountId>:log-group:/aws/bedrock-agentcore/runtimes/*:log-stream:*"
    },
    {
      "Sid": "CloudWatchLogsPutResourcePolicy",
      "Effect": "Allow",
      "Action": [
        "logs:PutResourcePolicy"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetricsPublish",
      "Effect": "Allow",
      "Resource": "*",
      "Action": "cloudwatch:PutMetricData",
      "Condition": {
        "StringEquals": {
          "cloudwatch:namespace": "bedrock-agentcore"
        }
      }
    },
    {
      "Sid": "AgentCoreWorkloadIdentity",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetWorkloadAccessTokenForJWT"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default/workload-identity/harness_<agentName>-*"
      ]
    },
    {
      "Sid": "AgentCoreBrowserDefault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartBrowserSession",
        "bedrock-agentcore:StopBrowserSession",
        "bedrock-agentcore:GetBrowserSession",
        "bedrock-agentcore:ListBrowserSessions",
        "bedrock-agentcore:UpdateBrowserStream",
        "bedrock-agentcore:ConnectBrowserAutomationStream",
        "bedrock-agentcore:ConnectBrowserLiveViewStream"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:aws:browser/*"
    },
    {
      "Sid": "AgentCoreCodeInterpreterDefault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartCodeInterpreterSession",
        "bedrock-agentcore:StopCodeInterpreterSession",
        "bedrock-agentcore:GetCodeInterpreterSession",
        "bedrock-agentcore:ListCodeInterpreterSessions",
        "bedrock-agentcore:InvokeCodeInterpreter"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:aws:code-interpreter/*"
    },
    {
      "Sid": "AgentCoreMemory",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateEvent",
        "bedrock-agentcore:DeleteEvent",
        "bedrock-agentcore:GetEvent",
        "bedrock-agentcore:ListEvents",
        "bedrock-agentcore:RetrieveMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:memory/harness_<agentNameAbbrv>_*"
    }
  ]
}

A AgentCore CLI cria uma função com essas permissões automaticamente quando você organiza um projeto de aproveitamento. A política acima é para casos em que você mesmo cria a função.

Para cargas de trabalho de produção, defina os Resource valores de acordo com os ARNs específicos que seu equipamento precisa, em vez de usar. "*"

Permissões adicionais para recursos opcionais

Abaixo estão exemplos de políticas que você pode acrescentar à sua função de execução com base nos recursos que seu equipamento usa. Siga o princípio do menor privilégio: conceda ao seu agente de controle somente as ferramentas e credenciais específicas de que ele precisa para inferência. Consulte Referência de espaço reservado as definições de espaços reservados.

Acesso ECR privado (imagens de contêiner personalizadas)

Adicione essa política quando seu equipamento usa uma imagem ECR privada para um contêiner personalizado.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECRImageAccess",
      "Effect": "Allow",
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:<ecrRegion>:<ecrAccountId>:repository/<ecrRepoName>"
    },
    {
      "Sid": "ECRTokenAccess",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    }
  ]
}

Modo VPC: extração gerenciada de imagens do ECR privado

Adicione essa política quando seu equipamento for executado no modo VPC. No modo VPC, o harness retira seu contêiner de aplicativos gerenciados de um repositório privado do Amazon ECR na região do harness (denominada). harness-<region> Esse pull usa ECR privado em vez do Amazon ECR Public, portanto, a função de execução precisa de permissões privadas de pull de ECR. Essa política é separada das permissões personalizadas da imagem do contêiner — ela se aplica à imagem AWS gerenciada mesmo quando você não fornece seu próprio contêiner.

O repositório pertence a uma conta de AWS serviço, portanto, a conta no ARN do repositório tem um curinga. As permissões de extração têm como escopo a região de harness.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EcrManagedImagePull",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchCheckLayerAvailability"
      ],
      "Resource": "arn:aws:ecr:<region>:*:repository/harness-*"
    },
    {
      "Sid": "EcrManagedImageToken",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    }
  ]
}

Certifique-se de que os endpoints de VPC necessários existam em sua VPC (consulte Configuração de rede): endpoints de interface para com.amazonaws.<region>.ecr.dkr e e com.amazonaws.<region>.ecr.api um endpoint de gateway para. com.amazonaws.<region>.s3

AgentCore Memória

Adicione essa política quando seu equipamento usa uma instância de memória de propriedade do cliente.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreMemory",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateEvent",
        "bedrock-agentcore:DeleteEvent",
        "bedrock-agentcore:GetEvent",
        "bedrock-agentcore:ListEvents",
        "bedrock-agentcore:RetrieveMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:memory/<memoryId>"
    }
  ]
}

AgentCore Navegador (personalizado)

Adicione essa política quando seu equipamento usa um recurso de navegador personalizado de propriedade do cliente.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreBrowserCustom",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartBrowserSession",
        "bedrock-agentcore:StopBrowserSession",
        "bedrock-agentcore:GetBrowserSession",
        "bedrock-agentcore:ListBrowserSessions",
        "bedrock-agentcore:UpdateBrowserStream",
        "bedrock-agentcore:ConnectBrowserAutomationStream",
        "bedrock-agentcore:ConnectBrowserLiveViewStream"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:browser-custom/<browserCustomId>"
    }
  ]
}

AgentCore Intérprete de código (personalizado)

Adicione essa política quando seu equipamento usa um intérprete de código personalizado de propriedade do cliente.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreCodeInterpreterCustom",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartCodeInterpreterSession",
        "bedrock-agentcore:StopCodeInterpreterSession",
        "bedrock-agentcore:GetCodeInterpreterSession",
        "bedrock-agentcore:ListCodeInterpreterSessions",
        "bedrock-agentcore:InvokeCodeInterpreter"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:code-interpreter-custom/<codeInterpreterCustomId>"
    }
  ]
}

AgentCore Gateway

Adicione essa política quando seu equipamento usa um gateway configurado com autenticação de entrada SigV4.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreGatewayAccess",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeGateway",
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:gateway/<gatewayId>"
    }
  ]
}

Fontes de habilidades no Amazon S3 e no Git

Adicione essa política quando seu equipamento buscar uma habilidade de uma fonte do Amazon S3. A função de execução lista e baixa os objetos de habilidade sob o prefixo bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreSkillS3Access",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<skillBucket>",
        "arn:aws:s3:::<skillBucket>/*"
      ]
    }
  ]
}

Para obter uma habilidade em um repositório Git privado, o equipamento lê um token de acesso pessoal de um provedor de credenciais de chave de API. Conceda a política de provedor de credenciais de chave de API mostrada abaixo para o provedor de credenciais que detém o token.

Provedor de credenciais de chave de API (referências de ARN de cabeçalho OpenAI, Gemini, LiteLM ou MCP)

Adicione essa política quando seu equipamento usa um provedor de credenciais de chave de API para fornecedores de modelos, como OpenAI, Gemini ou LiteLM.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreApiKeyTokenVaultDefault",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetResourceApiKey",
      "Resource": [
        "arn:aws:bedrock-agentcore:<region>:<accountId>:token-vault/default",
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default/workload-identity/harness_<agentName>-*"
      ]
    },
    {
      "Sid": "AgentCoreApiKeyTokenVaultPerKey",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetResourceApiKey",
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:token-vault/default/apikeycredentialprovider/<apiKeyName>"
    },
    {
      "Sid": "AgentCoreApiKeySecret",
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:<region>:<accountId>:secret:bedrock-agentcore-identity!default/apikey/<apiKeyName>-*"
    }
  ]
}

Provedor de credenciais OAuth2 (Gateway) OAuth-protected

Adicione essa política quando seu equipamento usa um provedor de credenciais OAuth2 para ferramentas de gateway. OAuth-protected

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreOAuth2TokenVaultDefault",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetResourceOauth2Token",
      "Resource": [
        "arn:aws:bedrock-agentcore:<region>:<accountId>:token-vault/default",
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default/workload-identity/harness_<agentName>-*"
      ]
    },
    {
      "Sid": "AgentCoreOAuth2TokenVaultPerProvider",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetResourceOauth2Token",
      "Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:token-vault/default/oauth2credentialprovider/<oauthProviderName>"
    },
    {
      "Sid": "AgentCoreOAuth2Secret",
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:<region>:<accountId>:secret:bedrock-agentcore-identity!default/oauth2/<oauthProviderName>-*"
    }
  ]
}

Referência de espaço reservado

Substitua os seguintes espaços reservados nas políticas acima por valores específicos para seu ambiente:

Tópicos relacionados