Use qualquer modelo, alterne no meio da sessão

Modelos e instruções

Defina um arnês uma vez com padrões para modelo, prompt do sistema, ferramentas, memória e limites de execução. Substitua qualquer um deles em uma única invocação quando quiser experimentar. O recurso de aproveitamento permanece inalterado; somente essa chamada usa as substituições.

Esse é o núcleo do modelo baseado em configuração: padrões no momento da criação, substituições no momento da invocação. Você pode testar combinações de model/prompt N/tool no tempo necessário para reimplantar uma vez.

exemplo

AWS CLI/boto3

O padrão é: create-harness


aws bedrock-agentcore-control create-harness \
  --harness-name "research-agent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --system-prompt '[{"text": "You are a research assistant."}]' \
  --tools '[{"type": "agentcore_browser", "name": "browser"}]'

Substituições por invocação:


response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    # These apply only to this call; the harness defaults stay intact
    model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-opus-4-5-20251101-v1:0"}},
    systemPrompt=[{"text": "You are a terse research assistant. One paragraph answers only."}],
    tools=[
        {"type": "agentcore_browser", "name": "browser"},
        {"type": "agentcore_code_interpreter", "name": "code_interpreter"},
    ],
    messages=[{"role": "user", "content": [{"text": "Summarize this paper as a bullet list."}]}],
)

Para alterar os padrões permanentemente, use. update-harness

AgentCore CLI

Defina padrões ao criar ou atualizar o chicote:


# Create a project if one does not already exist.
agentcore create

# Add a harness to the project
agentcore add harness \
  --name research-agent \
  --model-id us.anthropic.claude-sonnet-4-6-20250514-v1:0 \
  --system-prompt "You are a research assistant." \
  --tools agentcore-browser

agentcore deploy

Substituir em uma invocação:


# Switch the model for one call
agentcore invoke --harness research-agent \
  --model-id us.anthropic.claude-opus-4-5-20251101-v1:0 \
  "Summarize this research paper"

# Swap tools for one call
agentcore invoke --harness research-agent \
  --tools agentcore-browser,code-interpreter \
  "Plot the citation counts as a bar chart"

Substituível no momento da invocação:--model-id,,--tools,,--system-prompt,--max-iterations,--max-tokens,--harness-timeout,--skills. --allowed-tools --actor-id Adicione --verbose para imprimir eventos JSON de streaming bruto para depuração.

Para alterar os padrões permanentemente, edite app/<name>/harness.json e execute. agentcore deploy

Interactive

Execute agentcore em um diretório de projeto para abrir a TUI, selecione adicionar e escolha Harness. O assistente orienta você na configuração do modelo e da instrução, passo a passo.

Escolha seu fornecedor de modelos. Amazon Bedrock, OpenAI, Google Gemini e LiteLLM-compatible qualquer provedor são suportados, cada um com um modelo padrão.
Escolha o formato da API. Para Amazon Bedrock e OpenAI, selecione Converse Stream (padrão), Respostas ou Conclusões de bate-papo. As respostas e as conclusões do bate-papo são fornecidas pela Bedrock Mantle.
Se você selecionar LiteLM, o assistente solicitará os LiteLLM-specific campos: uma chave de API ARN opcional, uma URL base de API opcional para OpenAI-compatible gateways e parâmetros adicionais opcionais transmitidos ao provedor.

Continue com as etapas restantes (ambiente, memória, configurações avançadas) e confirme. Em seguida, corra agentcore deploy para se inscrever.

Use qualquer modelo, alterne no meio da sessão

Use modelos do Amazon Bedrock, OpenAI, Google Gemini ou outros fornecedores por meio do LiteLM, incluindo endpoints. OpenAI-compatible Troque de provedor entre turnos da mesma sessão e a conversa continua. O contexto é transferido.

Se você não especificar um modelo, o equipamento usa como padrão o Claude Sonnet 4.6 da Anthropic no Amazon Bedrock () global.anthropic.claude-sonnet-4-6 para que você possa começar imediatamente. Você pode alterar o padrão ou substituir por invocação a qualquer momento.

Armazene chaves de API de terceiros no cofre de tokens do AgentCore Identity como um provedor de credenciais de chave de API. O arnês puxa a chave no momento da invocação. Seu código de agente nunca vê credenciais brutas.

exemplo

AWS CLI/boto3

Registre uma chave de API com AgentCore Identity:


aws bedrock-agentcore-control create-api-key-credential-provider \
  --name my-openai-key \
  --api-key "$OPENAI_API_KEY"

Troque de provedor em turnos da mesma sessão:


# Turn 1: Bedrock (native Converse API)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-sonnet-4-5-20250514-v1:0"}},
    messages=[{"role": "user", "content": [{"text": "Analyze this codebase."}]}],
)

# Turn 2: Bedrock Mantle (OpenAI Responses format, no API key needed)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "bedrockModelConfig": {
            "modelId": "openai.gpt-4o",
            "apiFormat": "responses",
            "additionalParams": {"reasoning": {"effort": "high"}},
        }
    },
    messages=[{"role": "user", "content": [{"text": "Now suggest fixes for the top three issues."}]}],
)

# Turn 3: OpenAI model via Bedrock Mantle (no API key needed)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "openAiModelConfig": {
            "modelId": "gpt-5.4",
            "apiFormat": "responses",
            "endpoint": {"bedrockMantle": {}},
        }
    },
    messages=[{"role": "user", "content": [{"text": "Summarize the fixes as a bullet list."}]}],
)

dica

Use openAiModelConfig with "endpoint": {"bedrockMantle": {}} para chamar modelos OpenAI por meio do Amazon Bedrock Mantle — sem necessidade de chave de API, usa suas credenciais de função de execução. Use openAiModelConfig with apiKeyArn ao chamar diretamente o endpoint OpenAI.

AgentCore CLI

Adicione uma chave de API ao AgentCore Identity:


agentcore add credential --type api-key --name my-openai-key --api-key $OPENAI_API_KEY
agentcore deploy

Invoque com o Bedrock Mantle (formato de respostas, sem necessidade de chave de API):


SESSION_ID="$(uuidgen)"

# Turn 1: Bedrock Mantle (Responses format)
agentcore invoke --harness my-agent \
  --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
  --api-format responses \
  --session-id "$SESSION_ID" \
  "Analyze this codebase and identify performance bottlenecks."

Mude para o OpenAI diretamente na mesma sessão:


# Turn 2: OpenAI direct on the same session
agentcore invoke --harness my-agent \
  --model-provider open_ai \
  --model-id gpt-5.4 \
  --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-openai-key \
  --session-id "$SESSION_ID" \
  "Now suggest fixes for the top three issues."

Saiba mais: AgentCore Identidade, provedores de credenciais de chave de API.

Selecione o formato da API do modelo

Cada configuração dos modelos Amazon Bedrock e OpenAI aceita um campo apiFormat opcional que seleciona qual protocolo de API o equipamento usa para chamar o modelo.

ParabedrockModelConfig, apiFormat seleciona o protocolo da API e o endpoint Amazon Bedrock que o equipamento chama:

converse_stream- a API Amazon Bedrock Converse, servida pelo endpoint. bedrock-runtime Esse é o padrão.
responses- a API de OpenAI-compatible respostas, servida pelo bedrock-mantle endpoint.
chat_completions- a API de conclusão de OpenAI-compatible bate-papo, servida pelo bedrock-mantle endpoint.

O bedrock-mantle endpoint oferece suporte a um conjunto de modelos e recursos diferente do bedrock-runtime endpoint padrão. Para obter detalhes, consulte Endpoints suportados pelo Amazon Bedrock.

ParaopenAiModelConfig, apiFormat pode ser um dos seguintes:

responses- a API OpenAI Responses. Esse é o padrão.
chat_completions- a API de conclusão do OpenAI Chat.

Ambas as configurações também aceitam um additionalParams campo opcional. Provider-specific os parâmetros de additionalParams entrada são passados para o provedor do modelo inalterados.

Importante

Os parâmetros inseridos additionalParams podem alterar o comportamento do provedor, incluindo roteamento de endpoints, tratamento de credenciais e seleção de regiões. Se seu aplicativo encaminhar a configuração do modelo fornecida pelo chamador paraInvokeHarness, valide esses campos antes da invocação. Consulte Modelo de responsabilidade compartilhada.

exemplo

Aplique Amazon Bedrock Guardrails

Use o Amazon Bedrock Guardrails para filtrar conteúdo prejudicial ou bloquear tópicos negados nas entradas e saídas do modelo. Para aplicar uma grade de proteção a cada solicitação de modelo, adicione um guardrailConfig objeto a. bedrockModelConfig.additionalParams O arnês passa esse objeto para o Amazon Bedrock com cada solicitação de modelo.

Para usar o Amazon Bedrock Guardrails com o arnês, configure bedrockModelConfig com o formato da API. converse_stream Se você omitirapiFormat, o arnês será usado converse_stream por padrão. Defina essa configuração em CreateHarness ouUpdateHarness, ou substitua-a para uma chamada. InvokeHarness

O exemplo de Python a seguir chama InvokeHarness com uma configuração de guardrail. HARNESS_ARNSubstitua pelo ARN do chicote SESSION_ID e por um ID de sessão de tempo de execução exclusivo.


import boto3

client = boto3.client("bedrock-agentcore")
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "bedrockModelConfig": {
            "modelId": "us.amazon.nova-micro-v1:0",
            "apiFormat": "converse_stream",
            "additionalParams": {
                "guardrailConfig": {
                    "guardrailIdentifier": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456",
                    "guardrailVersion": "1",
                    "trace": "enabled_full",
                }
            },
        }
    },
    messages=[{"role": "user", "content": [{"text": "Help me plan a trip."}]}],
)

Para obter as permissões do modelo básico, consulte a política de função de execução. Adicione a seguinte declaração JSON à política de função de execução do harness:


{
  "Effect": "Allow",
  "Action": "bedrock:ApplyGuardrail",
  "Resource": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456"
}

Use uma grade de proteção na mesma AWS região da solicitação do modelo. Quando uma grade de proteção intervém, o fluxo de resposta é relatado guardrail_intervened como o motivo da parada.

Para obter mais informações sobre os campos de configuração do guardrail, consulte Usar um guardrail com a API Converse. Para obter mais informações sobre permissões do IAM, consulte Configurar permissões para usar o Amazon Bedrock Guardrails.

Use um modelo por meio do LiteLM

Use liteLlmModelConfig para entrar em contato com qualquer provedor compatível com o LiteLM, incluindo OpenAI-compatible endpoints. modelIdDefina como um ID de modelo prefixado pelo provedor LiteLM, como ou. gemini/gemini-2.5-pro anthropic/claude-sonnet-4-6

Os provedores que se autenticam com uma chave de API (como Google ou Anthropic) exigem. apiKeyArn Os modelos do Amazon Bedrock acessados com o bedrock/ prefixo usam as permissões da função de execução do harness e não precisam de uma chave de API.

modelId(obrigatório) - o ID do modelo com prefixo do provedor LiteLM.
apiKeyArn- o ARN da chave de API do provedor, armazenado no AgentCore Identity como um provedor de credenciais de chave de API. O endpoint deve aceitar essa chave de API.
apiBase- uma URL de endpoint personalizada para um OpenAI-compatible gateway, como um proxy ou endpoint auto-hospedado.
additionalParams- parâmetros específicos do provedor passados para o LiteLM inalterados. Isso inclui parâmetros que podem substituir endpoints (aws_bedrock_runtime_endpoint), assumir funções do IAM (aws_role_name) ou alterar o roteamento da solicitação. Consulte Modelo de responsabilidade compartilhada.

liteLlmModelConfigtambém aceita os topP campos opcionais maxTokenstemperature, e.

exemplo

Quando seu equipamento usa um provedor de credenciais de chave de API, conceda à função de execução permissão para ler a chave. Consulte Segurança e controles de acesso.

Para obter informações adicionais sobre a configuração do chicote, consulte o Documentação de API

Tópicos relacionados

Ferramentas- conecte ferramentas ao seu arnês
Memória- mantenha as conversas em todas as sessões
Controle o custo com limites- definir limites de execução e estratégias de truncamento

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Conceitos básicos

Ferramentas

Modelos e instruções

exemplo

Use qualquer modelo, alterne no meio da sessão

exemplo

dica

Selecione o formato da API do modelo

Importante

exemplo

nota

Aplique Amazon Bedrock Guardrails

Use um modelo por meio do LiteLM

exemplo

nota

Tópicos relacionados