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à.
# Inizia a usare Instances utilizzando AWS CLI o SDK
Questo tutorial illustra come ospitare un agente sul tipo di ** elaborazione ** Instances con l'interfaccia a riga di AWS comando (AWS CLI) e gli SDK. Devi prima creare un fornitore di [ capacità ](runtime-instances-how-it-works.md#runtime-instances-capacity-provider) che definisce l'infrastruttura Amazon Elastic Compute Cloud (Amazon EC2), quindi creare un runtime dell'agente che la utilizza e infine richiamare l'agente.
Per i prerequisiti, consulta Guida introduttiva alle [ istanze. ](runtime-instances-getting-started.md)
**Nota**
I nomi dei parametri in questi esempi seguono il modello del piano AgentCore di controllo. Per le forme autorevoli di richiesta e risposta, consulta [ Amazon Bedrock AgentCore Control API Reference. ](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)
## Fase 1: Creare un fornitore di capacità
Usa l'`CreateCapacityProvider`operazione per definire la tua infrastruttura EC2. La richiesta richiede un `permissionsConfiguration` (il ruolo IAM AgentCore utilizzato per gestire il fornitore di capacità) e uno `computeConfiguration` che descrive le istanze EC2 tramite un modello di avvio. L'esempio seguente crea un fornitore di capacità Linux con un singolo tipo di istanza consentito e un volume EBS persistente.
**Example**
1.
```
aws bedrock-agentcore-control create-capacity-provider \
--name "my_capacity_provider" \
--permissions-configuration '{
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
}' \
--compute-configuration '{
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"]
}
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"]
},
"lifecycleConfiguration": {
"maxLifetime": 3600
},
"volumes": [
{ "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
]
}
}'
```
1. Esempio in Python che utilizza boto3 per creare un fornitore di capacità.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_capacity_provider(
name="my_capacity_provider",
permissionsConfiguration={
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
},
computeConfiguration={
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"],
},
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"],
},
"lifecycleConfiguration": {
"maxLifetime": 3600,
},
"volumes": [
{"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
],
}
},
)
print(f"Capacity provider ARN: {response['capacityProviderArn']}")
```
Per eseguire carichi di lavoro GPU, includi un tipo di istanza GPU supportato. `allowedInstanceTypes` AgentCore esegue il provisioning dei driver GPU sull'istanza, in modo che le immagini standard dei container funzionino senza raggruppare i driver. Le famiglie supportate sono`g4dn`,`g5`,`g6`,`g6e`,`gr6`,, `g6f` `gr6f``g7e`, e. `inf2` Se includi un tipo di istanza di accelerazione di una famiglia non supportata, la richiesta ha esito negativo con un. `ValidationException` Per ulteriori informazioni, consulta [ Usare i tipi di istanza GPU. ](runtime-instances-how-it-works.md#runtime-instances-gpu)
Effettua il polling `GetCapacityProvider` fino a ottenere lo stato `READY` prima di associare il fornitore di capacità a un runtime. Se lo stato diventa`CREATE_FAILED`, `statusReason` ispeziona `statusCode` e determina la causa.
## Fase 2: Creare un runtime dell'agente sul fornitore di capacità
Crea un runtime dell'agente con un `capacityProviderConfiguration` riferimento al tuo fornitore di capacità. Per montare un volume definito sul fornitore di capacità nel file system dell'agente, aggiungete una `capacityProviderVolume` voce `filesystemConfigurations` che faccia riferimento al volume per nome. I percorsi di montaggio devono trovarsi in `/mnt` una singola sottodirectory (ad esempio,). `/mnt/scratch`
Il runtime dell'agente ha un proprio runtime`lifecycleConfiguration.maxLifetime`, che per impostazione predefinita è 28800 secondi (8 ore). Questo valore deve essere inferiore o uguale a `maxLifetime` quello impostato dal fornitore di capacità. `ec2Configuration.lifecycleConfiguration` Il fornitore di capacità nella Fase 1 imposta tale valore su 3600 secondi (1 ora), pertanto l'impostazione predefinita di 8 ore di runtime supererebbe tale valore e `CreateAgentRuntime` fallirebbe con un`ValidationException`. L'esempio seguente imposta quindi un tempo `maxLifetime` di esecuzione di 1800 secondi, che rientra nei limiti del fornitore di capacità.
**Nota**
Entrambe le risorse utilizzano un `lifecycleConfiguration` membro, ma sono strutture diverse. La versione del fornitore di capacità accetta `idleInstanceTimeout` `maxLifetime` e si applica all'istanza. La versione del runtime dell'agente richiede `idleRuntimeSessionTimeout` `maxLifetime` e si applica alla sessione. Per ulteriori informazioni, consulta [ Configurare le impostazioni del ciclo di AgentCore vita di Amazon Bedrock. ](runtime-lifecycle-settings.md)
Non passare `networkConfiguration` quando lo specifichi. `capacityProviderConfiguration` Il runtime di Instances eredita la propria rete da quella del fornitore di capacità`ec2Configuration.vpcConfiguration`, pertanto la specificazione di entrambi ha esito negativo con un. `ValidationException`
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "my_instances_agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--lifecycle-configuration '{
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800
}' \
--filesystem-configurations '[
{
"capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
}
]'
```
1. Esempio di Python che utilizza boto3 per creare un runtime dell'agente su Instances.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="my_instances_agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
},
lifecycleConfiguration={
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800,
},
filesystemConfigurations=[
{
"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
}
],
)
print(f"Agent runtime ARN: {response['agentRuntimeArn']}")
```
## Passaggio 3: richiama l'agente
Richiamate il runtime nello stesso modo in cui usereste un micro VM-backed runtime. Riutilizza lo stesso `runtimeSessionId` tra le chiamate per mantenere la sessione sulla stessa istanza. Ciò consente all'agente di accedere ai dati delle chiamate precedenti. Per co-localizzare gli agenti che collaborano, utilizza lo stesso `runtimeSessionId` su più runtime che condividono un fornitore di capacità.
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
Il `payload` parametro è un blob binario e la AWS CLI prevede che i blob siano codificati in base64 per impostazione predefinita. Il passaggio di un JSON non elaborato in linea, ad esempio, ha esito negativo sul lato client e genera un errore prima che la richiesta `--payload '{"prompt": "…"}'` raggiunga il servizio. `Invalid base64` Il `fileb://` modulo utilizzato qui legge il file come binario indipendentemente dall'`cli_binary_format`impostazione, quindi evita la fase di codifica.
La risposta dell'agente è un blob in streaming che la AWS CLI scrive nel file di output indicato come ultimo argomento, in questo esempio. `response.json` Lo standard output contiene solo i `statusCode` campi`runtimeSessionId`,`contentType`, e, quindi leggi il file di output per vedere cosa ha restituito il tuo agente.
AWS SDK
1. Esempio di Python che utilizza boto3 per richiamare il runtime di un agente sulle istanze.
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000", # 33+ chars; reuse to keep the session
payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
qualifier="DEFAULT",
)
print("Agent response:", json.loads(response["response"].read()))
```
`runtimeSessionId`Deve contenere almeno 33 caratteri.
La prima chiamata per una nuova sessione esegue il provisioning di un'istanza EC2 nel tuo account e avvia l'agente, quindi in genere richiede più tempo rispetto alle chiamate successive. Le chiamate successive alla stessa sessione riutilizzano l'istanza in esecuzione e ritornano molto più velocemente.
AgentCore esegue il provisioning di queste istanze come istanze gestite da [ Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html), che per impostazione predefinita sono nascoste `DescribeInstances` e visualizzate dalla console EC2. Una semplice `aws ec2 describe-instances` chiamata non li elenca. Per visualizzarli, includi le risorse gestite:
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"
```
Per ulteriori informazioni sulla gestione della visibilità delle istanze, consulta l'impostazione di visibilità delle risorse [ gestite](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings).
## Co-locate più agenti su un'istanza
Quando i runtime di due agenti fanno riferimento allo ** stesso fornitore di ** capacità e li richiami con ** lo stesso **`runtimeSessionId`, entrambi gli agenti vengono eseguiti sulla stessa istanza EC2. Lì, possono condividere il volume configurato nella configurazione del loro file system. Gli agenti collaborano leggendo e scrivendo file su quel volume condiviso: ogni agente viene richiamato in modo indipendente e non condivide altrimenti lo stato. Ad esempio, un test runner può scrivere i risultati sul volume e un analizzatore di codice richiamato nella stessa sessione può quindi leggerli. Per il confine tra gli agenti su un'istanza condivisa, vedi Modello di [ sicurezza e autorizzazioni per le istanze di runtime. ](runtime-instances-security.md)
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"
# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
qualifier="DEFAULT",
)
# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
qualifier="DEFAULT",
)
```
Ogni agente viene eseguito con le proprie credenziali IAM derivate dal ruolo di esecuzione del relativo runtime, quindi puoi concedere agli agenti che collaborano autorizzazioni diverse sebbene condividano la stessa istanza. Tuttavia, poiché gli agenti sulla stessa istanza non sono isolati l'uno dall'altro, qualsiasi agente può potenzialmente leggere le credenziali di un altro agente. Co-locate solo agenti che si fidano reciprocamente. Per ulteriori informazioni, consulta Modello [ di sicurezza e autorizzazioni per le istanze di runtime. ](runtime-instances-security.md)
## Pulizia: interrompi ed elimina le sessioni
**avvertimento**
Per evitare addebiti continui per le istanze Amazon EC2 e i volumi Amazon EBS di cui hai effettuato il provisioning nel tuo account, elimina le sessioni e i fornitori di capacità che non ti servono più al termine di questo tutorial.
Una sessione può ospitare più runtime di agenti sulla stessa istanza, quindi AgentCore fornisce due operazioni distinte:
+ **Arresta il runtime di un agente in una sessione**: `StopRuntimeSession` interrompe il runtime di un singolo agente all'interno di una sessione, identificato dall'ARN di runtime e dall'ID della sessione. I runtime degli altri agenti che condividono la stessa sessione e istanza non sono interessati.
+ **Elimina una sessione**: `DeleteCapacityProviderSession` elimina l'intera sessione e rimuove le risorse EC2 create nel tuo account (istanza, interfaccia di rete ed eventuali volumi EBS persistenti), in modo da non incorrere in costi di infrastruttura e storage.
Per interrompere il runtime di un agente specifico in una sessione, richiama l'[StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html)operazione con l'ARN di runtime e l'ID di sessione.
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. Esempio in Python che utilizza boto3 per interrompere una sessione di runtime.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
Per eliminare una sessione e annullare il provisioning di tutte le sue risorse, inclusi eventuali volumi EBS persistenti, chiama `DeleteCapacityProviderSession` con l'ID del fornitore di capacità e l'ID della sessione. L'operazione è idempotente e asincrona: ritorna immediatamente mentre AgentCore termina l'istanza ed elimina i volumi in background.
Gli ID di sessione sono valori forniti al momento della chiamata e non esiste alcuna operazione che elenca le sessioni su un fornitore di capacità. Tieni traccia dei `runtimeSessionId` valori utilizzati in modo da poter eliminare ogni sessione in un secondo momento. Se non li hai più, puoi trovare le istanze ancora in esecuzione e quindi eliminare il fornitore di capacità per annullare il provisioning di tutte le sue sessioni:
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
--query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. Esempio in Python che utilizza boto3 per eliminare una sessione del fornitore di capacità.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## Eliminare un fornitore di capacità
Quando non hai più bisogno di un fornitore di capacità, eliminalo con l'`DeleteCapacityProvider`operazione. L'eliminazione di un fornitore di capacità interrompe ed elimina tutte le sessioni associate e la relativa archiviazione persistente, quindi serve anche come metodo per ripulire le sessioni i cui ID non sono più disponibili. Non è necessario eliminare prima le sessioni. Tuttavia, è necessario rimuovere i runtime che fanno riferimento al fornitore di capacità: eliminare prima le versioni, gli endpoint o i runtime associati, altrimenti la richiesta di eliminazione ha esito negativo con un. `ValidationException` L'operazione è asincrona; identifica il fornitore di capacità tramite il suo ID.
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. Esempio in Python che utilizza boto3 per eliminare un fornitore di capacità.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```