Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Configurazione di un agente in linea al runtime
Puoi configurare e richiamare un agente Amazon Bedrock in linea in modo dinamico in fase di esecuzione utilizzando l'API. [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) L’utilizzo di un agente in linea offre la flessibilità necessaria per specificare le funzionalità dell’agente, come modelli di fondazione, istruzioni, gruppi di azioni, guardrail e knowledge base, contemporaneamente all’invocazione dell’agente stesso. Non è necessario predefinire le funzionalità dell’agente prima di poterlo utilizzare.
Di seguito sono riportati alcuni casi d’uso in cui l’utilizzo di agenti in linea può essere utile, in quanto offre la flessibilità di configurare l’agente al momento dell’invocazione.
+ Esegui sperimentazioni rapide provando varie funzionalità dell’agente con diverse configurazioni e aggiornando dinamicamente gli strumenti disponibili per il tuo agente senza creare agenti separati.
+ Invoca dinamicamente un agente per eseguire attività specifiche senza creare nuove versioni dell’agente o preparare l’agente.
+ Esegui query semplici o utilizza l’interprete di codice per attività semplici creando e invocando l’agente al runtime.
+ Crea più agenti in una configurazione di [collaborazione multiagente](agents-multi-agent-collaboration.md) per collaborare su un’attività o una conversazione.
Per utilizzare la collaborazione tra più agenti, puoi creare i tuoi agenti nelle seguenti combinazioni utilizzando agenti in linea. APIs
**Tipi di agente**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/agents-create-inline.html)
**Regioni e modelli supportati**
Puoi utilizzare qualsiasi modello di fondazione supportato da Agenti per Amazon Bedrock per configurare l’agente in linea e invocarlo in tutte le Regioni in cui è supportato Agent per Amazon Bedrock. Per ulteriori informazioni su modelli e Regioni supportati da Agent per Amazon Bedrock, consulta:
+ [Regioni supportate per Agent per Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-supported.html)
+ [Supporto dei modelli per funzionalità](https://docs.aws.amazon.com//bedrock/latest/userguide/models-features.html)
Con gli agenti in linea puoi passare da un modello all’altro. Ti consigliamo di passare tra modelli che appartengono alla stessa famiglia. Il passaggio tra modelli che appartengono a famiglie diverse potrebbe causare comportamenti incoerenti ed errori.
La configurazione e l’invocazione di un agente in linea non sono al momento supportate nella console Amazon Bedrock.
## Linee guida per l’utilizzo di modelli di prompt avanzati per agenti in linea
+ **Modelli di prompt di base**: per impostazione predefinita, Amazon Bedrock utilizza il modello di prompt di base predefinito per l’agente in linea e i prompt possono essere modificati in background in qualsiasi momento. Ciò potrebbe rendere le risposte incoerenti. Se desideri ottenere risposte coerenti alle query, personalizza il comportamento dell’agente in linea sovrascrivendo la logica nel modello di prompt di base predefinito con le tue configurazioni. Per ulteriori informazioni, consulta [Modelli di prompt avanzati](https://docs.aws.amazon.com//bedrock/latest/userguide/advanced-prompts-templates.html).
+ **Crittografia**: utilizza `customer managed key ` per crittografare i dettagli della sessione a riposo o in fase di archiviazione. Se una sessione viene avviata con una chiave gestita dal cliente, questa sarà richiesta per tutte le richieste future effettuate per la stessa sessione. L’utilizzo di una chiave gestita dal cliente diversa per le stesse sessioni comporterà un’eccezione.
+ **Condivisione della sessione**: d’ora in poi tutte le sessioni saranno a livello di account anziché a livello di ruolo. Puoi isolare le sessioni a livello di agente specificando un valore univoco per `agentName`.
+ **Stato delle sessioni in linea**: gli attributi all’interno di `InlineSessionState` vengono mantenuti per tutta la sessione. Utilizza gli attributi per fornire contesto aggiuntivo al modello e per [prompt in pochi passaggi](https://docs.aws.amazon.com//bedrock/latest/userguide/what-is-a-prompt.html#few-shot-prompting-vs-zero-shot-prompting).
# Prerequisiti
**Nota**
La configurazione e l’invocazione di una funzionalità di agente in linea è una versione in anteprima per Amazon Bedrock ed è soggetta a modifiche.
Completa i seguenti prerequisiti prima di invocare l’agente in linea:
1. Decidi il modello di fondazione che desideri utilizzare per configurare l’agente in linea, la Regione in cui desideri invocare l’agente e un’istruzione che indichi all’agente in linea cosa deve fare.
1. Crea o prepara una o più delle seguenti proprietà di Agent per Amazon Bedrock che desideri utilizzare per il l’agente in linea.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/inline-agent-prereq.html)
1. Crea un ruolo AWS Identity and Access Management (IAM) e associa al ruolo la policy menzionata in questo passaggio.
Prima di poter invocare un agente in linea, devi creare un ruolo IAM che fornisca le autorizzazioni necessarie per utilizzare l’API `InvokeInlineAgent` e accedere a risorse come funzioni Lambda, knowledge base e modelli di fondazione.
Crea un ruolo di servizio personalizzato per l’agente in linea seguendo le fasi in [Creazione di un ruolo per delegare le autorizzazioni a un utente IAM](https://docs.aws.amazon.com//bedrock/latest/userguide/getting-started.html). Dopo aver creato il ruolo IAM, collega al ruolo la seguente policy.
**Nota**
Come procedura consigliata per motivi di sicurezza, sostituisci *\$1\$1region\$1**\$1\$1account-id\$1*, e *\$1.ids* con Region, l'ID dell'account e gli ID delle risorse specifici dopo averli creati.
# Invocare un agente in linea
**Nota**
Le funzioni di configurazione e invocazione di una funzionalità di agente in linea sono in una versione in anteprima per Amazon Bedrock ed sono soggette a modifiche.
Prima di invocare il tuo agente in linea, assicurati di aver completato i [prerequisiti](https://docs.aws.amazon.com//bedrock/latest/userguide/inline-agent-prereq.html).
Per richiamare un agente in linea, invia una richiesta [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html)API con un [endpoint di runtime Agents for Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt) e includi almeno i seguenti campi.
****
| Campo | Caso d’uso |
| --- | --- |
| instruction | Fornisci istruzioni che indicano all’agente in linea cosa deve fare e come deve interagire con gli utenti. |
| foundationModel | Specifica un [modello di fondazione](https://docs.aws.amazon.com//bedrock/latest/userguide/foundation-models-reference.html) da utilizzare per l’orchestrazione da parte dell’agente in linea che hai creato. Ad esempio, anthropic claude, meta Llama3.1 e così via. |
| sessionId | Identificatore univoco della sessione. Utilizza lo stesso valore per tutte le richieste per continuare la stessa conversazione. |
I seguenti campi sono facoltativi:
****
| Campo | Caso d’uso |
| --- | --- |
| actionGroups | Elenco di gruppi di azione con ciascun gruppo di azioni che definisce le azioni che l’agente in linea può eseguire. |
| knowledgeBases | Associazioni di knowledge base all’agente in linea per potenziare la risposta generata dal modello. |
| guardrailConfiguration | Configura i guardrail per bloccare argomenti, prevenire allucinazioni e implementare misure di sicurezza per la tua applicazione. |
| agentCollaboration | Definisce il modo in cui l’agente collaboratore gestisce le informazioni tra più agenti collaboratori per coordinare una risposta finale. L’agente collaboratore può anche essere il supervisore. |
| collaboratorConfigurations | Configurazioni per l’agente collaboratore. |
| collaboratori | Elenco degli agenti collaboratori. |
| promptOverrideConfiguration | Configurazioni per prompt avanzati utilizzati per sovrascrivere i prompt predefiniti. |
| enableTrace | Specifica se attivare o meno la traccia per monitorare il processo di ragionamento dell’agente in linea. |
| Secondi di sessione di inattività TTLIn | Specifica la durata dopo la quale l’agente deve terminare la sessione ed eliminare tutte le informazioni archiviate. |
| customerEncryptionKeyArn | Specifica l’ARN di una chiave KMS per crittografare le risorse dell’agente. |
| endSession | Specifica se terminare o meno la sessione con l’agente in linea. |
| inlineSessionState | Parametri che specificano i vari attributi di una sessione. |
| inputText | Specifica il testo del prompt da inviare all’agente. |
| reasoning\$1config | Per abilitare il ragionamento del modello, così che spieghi come ha raggiunto le sue conclusioni. Utilizzalo all’interno di un campo additionalModelRequestFields. È necessario specificare il numero di budget\$1tokens utilizzati per il ragionamento del modello, ovvero un sottoinsieme dei token di output. Per ulteriori informazioni, consulta [Migliorare le risposte del modello con il ragionamento basato su modello](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html). |
Il seguente esempio di API `InvokeInlineAgent` fornisce configurazioni complete degli agenti in linea, tra cui il modello di fondazione, le istruzioni, i gruppi di azioni con interprete di codice, i guardrail e le knowledge base.
```
response = bedrock_agent_runtime.invoke_inline_agent(
// Initialization parameters: cannot be changed for a conversation
sessionId='uniqueSessionId',
customerEncryptionKeyArn: String,
// Input
inputText="Hello, can you help me with a task?",
endSession=False,
enableTrace=True,
// Agent configurations
foundationModel='anthropic.claude-3-7-sonnet-20250219-v1:0',
instruction="You are a helpful assistant...",
actionGroups=[
{
'name': 'CodeInterpreterAction',
'parentActionGroupSignature': 'AMAZON.CodeInterpreter'
},
{
'actionGroupName': 'FetchDetails',
'parentActionGroupSignature': '',
"actionGroupExecutor": { ... },
"apiSchema": { ... },
"description": "string",
"functionSchema": { ... }
}
],
knowledgeBases=[
{
knowledgeBaseId: "string",
description: 'Use this KB to get all the info',
retrievalConfiguration: {
vectorSearchConfiguration: {
filter: { ... },
numberOfResults: number,
overrideSearchType: "string"
}
}
}
],
guardrailConfiguration={
guardrailIdentifier: 'BlockEverything',
gurardrailVersion: '1.0'
},
promptOverrideConfiguration: {...}
// session properties: persisted throughout conversation
inlineSessionState = {
sessionAttributes = { 'key': 'value' },
promptSessionAttributes = {k:v},
returnControlInvocationResults = {...},
invocationId = 'abc',
files = {...},
}
}
```
È possibile includere i parametri di ragionamento del modello nella richiesta. Di seguito è illustrato un esempio di un singolo prompt che attiva il ragionamento del modello in `additionalModelRequestFields`.
```
{
"basePromptTemplate": " ... ",
"inferenceConfiguration": {
"stopSequences": [
""
]
},
"parserMode": "DEFAULT",
"promptCreationMode": "DEFAULT",
"promptState": "DISABLED",
"promptType": "ORCHESTRATION",
"additionalModelRequestFields":
"reasoning_config": {
"type": "enabled",
"budget_tokens": 1024
}
}
```