Use qualquer modelo, alterne no meio da sessão

Modelos e instruções

Defina um equipamento 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 harness 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 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 os padrões ao criar ou atualizar o chicote:


# Create an empty project if one does not already exist
agentcore create --project-name ResearchAgentProject --no-agent
cd ResearchAgentProject

# Add a harness to the project
agentcore add harness \
  --name research-agent \
  --model-id us.anthropic.claude-sonnet-4-6 \
  --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,agentcore_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ê passo a passo na configuração do modelo e da instrução.

Escolha seu fornecedor de modelos. Amazon Bedrock, OpenAI, Google Gemini e qualquer LiteLLM-compatible provedor são compatíveis, 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: um ARN de chave de API opcional, um 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 da 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 continuará. O contexto é transferido.

Se você não especificar um modelo, o padrão do equipamento é 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 da 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 com "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 com apiKeyArn ao chamar diretamente o endpoint OpenAI.

AgentCore CLI

Adicione uma chave de API à AgentCore Identidade:


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

No diretório do AgentCore projeto que você criou anteriormente, adicione um segundo equipamento que use o formato de respostas. Em seguida, implante o projeto:


agentcore add harness \
  --name my-agent \
  --model-provider bedrock \
  --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
  --api-format responses
agentcore deploy

Invoque com Bedrock Mantle:


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 \
  --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 uma das configurações dos modelos Amazon Bedrock e OpenAI aceita um apiFormat campo 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, fornecida pelo endpoint. bedrock-runtime Esse é o padrão.
responses- a API de OpenAI-compatible respostas, fornecida pelo bedrock-mantle endpoint.
chat_completions- a API OpenAI-compatible Chat Complements, fornecida pelo bedrock-mantle endpoint.

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

PoisopenAiModelConfig, apiFormat pode ser um dos seguintes:

responses- a API OpenAI Responses. Esse é o padrão.
chat_completions- a API OpenAI Chat Complements.

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

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 fornecido pelo chamador paraInvokeHarness, valide esses campos antes da invocação. Consulte Modelo de responsabilidade compartilhada.

exemplo

Aplique os guardrails Amazon Bedrock

Use o Amazon Bedrock Guardrails para filtrar conteúdo nocivo 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 chicote passa esse objeto para a Amazon Bedrock com cada solicitação de modelo.

Para usar o Amazon Bedrock Guardrails com o chicote, configure bedrockModelConfig com o formato da API. converse_stream Se você omitirapiFormat, o chicote será usado converse_stream por padrão. Defina essa configuração em CreateHarness ou UpdateHarness 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 seu equipamento e por um ID SESSION_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 da função de execução. Adicione a seguinte instruçã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 as permissões do IAM, consulte Configurar permissões para usar o Amazon Bedrock Guardrails.

Use um modelo por meio do LiteLM

Use liteLlmModelConfig para alcançar 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 prefixado pelo provedor LiteLM.
apiKeyArn- o ARN da chave de API do provedor, armazenado em AgentCore Identity como um provedor de credenciais de chave de API. O endpoint deve aceitar essa chave de API.
apiBase- um URL de endpoint personalizado para um OpenAI-compatible gateway, como um proxy ou um 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 de solicitações. 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 permissão à função de execuçã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- persistir nas conversas entre 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 os guardrails Amazon Bedrock

Use um modelo por meio do LiteLM

exemplo

nota

Tópicos relacionados