Usa qualsiasi modello, cambia a metà sessione

Modelli e istruzioni

Definisci un harness una sola volta con i valori predefiniti per il modello, il prompt di sistema, gli strumenti, la memoria e i limiti di esecuzione. Sovrascrivi uno qualsiasi di questi in una singola chiamata quando vuoi sperimentare. La risorsa harness rimane invariata; solo quella chiamata utilizza le sostituzioni.

Questo è il fulcro del modello basato sulla configurazione: le impostazioni predefinite al momento della creazione, le sostituzioni al momento dell'invocazione. È possibile testare le combinazioni model/prompt N/tool nel tempo necessario per la ridistribuzione una volta.

Esempio

AWS CLI/boto3

L'impostazione predefinita è: 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"}]'

Sostituzioni per chiamata:


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."}]}],
)

Per modificare i valori predefiniti in modo permanente, usa. update-harness

AgentCore CLI

Imposta le impostazioni predefinite quando crei o aggiorni l'imbracatura:


# 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

Sostituisci un'invocazione:


# 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"

Sostituibile al momento della chiamata:--model-id,,,,,,--tools,--system-prompt,--max-iterations. --max-tokens --harness-timeout --skills --allowed-tools --actor-id Aggiungi --verbose alla stampa eventi JSON in streaming non elaborati per il debug.

Per modificare le impostazioni predefinite in modo permanente, modifica ed esegui. app/<name>/harness.json agentcore deploy

Interactive

Esegui agentcore in una directory di progetto per aprire il TUI, seleziona aggiungi, quindi scegli Harness. La procedura guidata guida l'utente passo dopo passo nella configurazione del modello e delle istruzioni.

Scegliete il fornitore del modello. Sono supportati Amazon Bedrock, OpenAI, Google Gemini e qualsiasi LiteLLM-compatible fornitore, ognuno con un modello predefinito.
Scegli il formato API. Per Amazon Bedrock e OpenAI, seleziona Converse Stream (impostazione predefinita), Responses o Chat Completions. Le risposte e i completamenti delle chat sono forniti da Bedrock Mantle.
Se si seleziona LiteLM, la procedura guidata richiede i LiteLLM-specific campi: una chiave API ARN opzionale, un URL di base API opzionale per i OpenAI-compatible gateway e parametri aggiuntivi opzionali trasmessi al provider.

Continua con i passaggi rimanenti (ambiente, memoria, impostazioni avanzate) e conferma. Quindi corri agentcore deploy per candidarti.

Usa qualsiasi modello, cambia a metà sessione

Usa i modelli di Amazon Bedrock, OpenAI, Google Gemini o altri provider tramite LiteLLM, compresi gli endpoint. OpenAI-compatible Cambia provider tra turni della stessa sessione e la conversazione continua. Il contesto viene trasferito.

Se non specifichi un modello, l'impostazione predefinita è Claude Sonnet 4.6 di Anthropic su Amazon Bedrock ()global.anthropic.claude-sonnet-4-6, in modo da poter iniziare immediatamente. Puoi modificare l'impostazione predefinita o sostituirla per chiamata in qualsiasi momento.

Archivia le chiavi API di terze parti nel token vault di AgentCore Identity come fornitore di credenziali per le chiavi API. L'imbracatura estrae la chiave al momento della chiamata. Il codice del tuo agente non vede mai le credenziali grezze.

Esempio

AWS CLI/boto3

Registra una chiave API con AgentCore Identity:


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

Cambia provider tra i turni della stessa sessione:


# 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."}]}],
)

Suggerimento

Usa openAiModelConfig with "endpoint": {"bedrockMantle": {}} per chiamare i modelli OpenAI tramite Amazon Bedrock Mantle: non è richiesta alcuna chiave API, utilizza le credenziali del tuo ruolo di esecuzione. Usalo openAiModelConfig con apiKeyArn quando chiami direttamente l'endpoint OpenAI.

AgentCore CLI

Aggiungi una chiave API a AgentCore Identity:


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

Dalla directory del AgentCore progetto che hai creato in precedenza, aggiungi un secondo harness che utilizza il formato Responses. Quindi distribuisci il progetto:


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

Invoca con 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."

Passa direttamente a OpenAI nella stessa sessione:


# 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."

Per saperne di più: AgentCore identità, fornitori di credenziali chiave API.

Seleziona il formato API del modello

Le configurazioni dei modelli Amazon Bedrock e OpenAI accettano ciascuna un apiFormat campo opzionale che seleziona il protocollo API utilizzato dall'harness per chiamare il modello.

ForbedrockModelConfig, apiFormat seleziona sia il protocollo API che l'endpoint Amazon Bedrock che l'harness chiama:

converse_stream- l'API Amazon Bedrock Converse, fornita dall'endpoint. bedrock-runtime Questa è l’impostazione predefinita.
responses- l'API OpenAI-compatible Responses, fornita dall'endpoint. bedrock-mantle
chat_completions- l'API OpenAI-compatible Chat Completions, fornita dall'endpoint. bedrock-mantle

L'bedrock-mantleendpoint supporta un set di modelli e funzionalità diverso rispetto all'endpoint predefinito. bedrock-runtime Per informazioni dettagliate, consulta Endpoint supportati da Amazon Bedrock.

PerchéopenAiModelConfig, apiFormat può essere uno dei seguenti:

responses- l'API OpenAI Responses. Questa è l’impostazione predefinita.
chat_completions- l'API OpenAI Chat Completions.

Entrambe le configurazioni accettano anche un campo opzionale. additionalParams Provider-specific i parametri inseriti additionalParams vengono trasmessi al fornitore del modello senza modifiche.

Importante

I parametri inseriti additionalParams possono alterare il comportamento del provider, tra cui il routing degli endpoint, la gestione delle credenziali e la selezione della regione. Se l'applicazione inoltra la configurazione del modello fornita dal chiamante a, convalida questi campi prima di InvokeHarness richiamarli. Consulta Modello di responsabilità condivisa.

Esempio

Applica Amazon Bedrock Guardrails

Usa Amazon Bedrock Guardrails per filtrare i contenuti dannosi o bloccare gli argomenti negati negli input e negli output del modello. Per applicare un guardrail a ogni richiesta di modello, aggiungi un oggetto a. guardrailConfig bedrockModelConfig.additionalParams L'imbracatura trasmette questo oggetto ad Amazon Bedrock con ogni richiesta di modello.

Per utilizzare Amazon Bedrock Guardrails con il cablaggio, esegui la configurazione con il formato API. bedrockModelConfig converse_stream Se ometti, l'imbracatura utilizza per apiFormat impostazione predefinita. converse_stream Imposta questa configurazione su CreateHarness o o UpdateHarness sovrascrivila per una chiamata in entrata. InvokeHarness

Il seguente esempio di Python chiama InvokeHarness con una configurazione guardrail. Sostituiscilo HARNESS_ARN con il tuo harness ARN e SESSION_ID con un ID di sessione di runtime univoco.


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."}]}],
)

Per le autorizzazioni del modello di base, consulta la politica del ruolo di esecuzione. Aggiungi la seguente dichiarazione JSON alla policy del ruolo di esecuzione di Harness:


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

Usa un guardrail nella stessa AWS regione della richiesta del modello. Quando interviene un guardrail, il flusso di risposta riporta guardrail_intervened come motivo dell'arresto.

Per ulteriori informazioni sui campi di configurazione del guardrail, consulta Utilizzare un guardrail con l'API Converse. Per ulteriori informazioni sulle autorizzazioni IAM, consulta Configurare le autorizzazioni per utilizzare Amazon Bedrock Guardrails.

Usa un modello tramite LiteLLM

liteLlmModelConfigUsalo per raggiungere qualsiasi fornitore supportato da LiteLLM, compresi gli endpoint. OpenAI-compatible Impostato su un modelId ID modello con prefisso del provider LiteLM, ad esempio o. gemini/gemini-2.5-pro anthropic/claude-sonnet-4-6

I provider che eseguono l'autenticazione con una chiave API (come Google o Anthropic) richiedono. apiKeyArn I modelli Amazon Bedrock a cui si accede con il bedrock/ prefisso utilizzano le autorizzazioni del ruolo Harness Execution e non necessitano di una chiave API.

modelId(obbligatorio): l'ID del modello con prefisso del provider LiteLM.
apiKeyArn- l'ARN della chiave API del provider, memorizzato in AgentCore Identity come fornitore di credenziali di chiave API. L'endpoint deve accettare questa chiave API.
apiBase- un URL di endpoint personalizzato per un OpenAI-compatible gateway, ad esempio un proxy o un endpoint ospitato autonomamente.
additionalParams- i parametri specifici del provider sono stati trasmessi a LiteLLM invariati. Ciò include parametri che possono sovrascrivere endpoint (aws_bedrock_runtime_endpoint), assumere ruoli IAM () o alterare il routing delle richieste. aws_role_name Consulta Modello di responsabilità condivisa.

liteLlmModelConfigaccetta anche i campi opzionali maxTokens etemperature. topP

Esempio

Quando il tuo harness utilizza un fornitore di credenziali per chiavi API, concedi al ruolo di esecuzione l'autorizzazione a leggere la chiave. Consulta Sicurezza e controlli degli accessi.

Per ulteriori informazioni sulla configurazione del cablaggio, consulta Documentazione API

Argomenti correlati

Tools (Strumenti)- collega gli strumenti all'imbracatura
Memoria- persistere le conversazioni tra le sessioni
Controlla i costi con limiti- impostare limiti di esecuzione e strategie di troncamento

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Nozioni di base

Tools (Strumenti)

Modelli e istruzioni

Esempio

Usa qualsiasi modello, cambia a metà sessione

Esempio

Suggerimento

Seleziona il formato API del modello

Importante

Esempio

Nota

Applica Amazon Bedrock Guardrails

Usa un modello tramite LiteLLM

Esempio

Nota

Argomenti correlati