Definire uno schema di metadati personalizzato

La migrazione è ora aperta

AWS Agent Registry è stato lanciato con il nuovo agent-registry namespace. Il supporto per lo spazio dei bedrock-agentcore nomi di anteprima pubblica verrà interrotto il 30 ottobre 2026. Per le istruzioni sulla migrazione, consulta la Guida completa alla migrazione del registro.

Utilizza metadati personalizzati per aggiungere campi personalizzati ai record di un registro, ad esempio un team proprietario, uno stato di revisione o una classificazione dei dati. I campi vengono definiti una volta nel registro. Quindi, quando crei o modifichi un record, li compili.

Si definiscono due tipi di campi:

• Attributi comuni: campi disponibili per i record di ogni tipo di record, definiti nello schema predefinito (defaultSchemanell'API). Il fatto che un record debba avere un valore dipende dall'impostazione Richiesto del campo.

• Campi relativi al tipo di record: campi aggiuntivi per un tipo di record, ad esempio server o agenti Model Context Protocol (MCP). Per l'elenco dei tipi di record, vedere Tipi di record e descrittori supportati.

Un record può contenere gli attributi comuni più i campi relativi al tipo di record. Utilizza gli attributi comuni per tutto ciò che desideri filtrare o riportare in tutti i record.

Esempio

Ogni record di questo registro necessita di un proprietario e può avere una classificazione dei dati. I record degli agenti necessitano inoltre di una famiglia di modelli e di una classificazione e possono essere classificati comerestricted.

Attributi comuni:

{
  "type": "object",
  "properties": {
    "owner": {"type": "string"},
    "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential"]}
  },
  "required": ["owner"]
}

Campi perAGENT:

{
  "type": "object",
  "properties": {
    "modelFamily": {"type": "string"},
    "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential", "restricted"]}
  },
  "required": ["modelFamily", "dataClassification"]
}

I record possono quindi contenere:

Tipo di record	Campi	Richiesto	Valori consentiti per dataClassification
Agente	owner, modelFamily, dataClassification	Tutti e tre	public, internal, confidential, restricted
Tutti gli altri tipi	owner, dataClassification	owner	public, internal, confidential

I campi Agent non si ripetonoowner, perché ogni tipo di record ottiene già gli attributi comuni. Si ripetonodataClassification. Ciò rende il campo obbligatorio per gli agenti e consente il valore aggiuntorestricted. Per modificare un attributo comune per un tipo di record come questo, includilo nei campi di quel tipo di record con lo stesso tipo e tutti i valori consentiti. Puoi aggiungere valori consentiti e renderli obbligatori.

Definire lo schema

Console

1. Aprire la pagina dei dettagli del registro nella console di AWS Agent Registry.

2. Nella sezione Schema di metadati personalizzato, scegli Gestisci schema.

3. In Attributi comuni, scegli Aggiungi campo per ogni campo che ogni record dovrebbe avere e inserisci:

   1. Nome: inizia con una lettera. Lettere_, numeri e-. Fino a 64 caratteri.

   2. Tipo: Testo, Enum (un elenco di valori consentiti), URL o booleano.

   3. Valori consentiti: per un campo Enum, inserisci tutti i valori che i record possono utilizzare: da 1 a 25 valori, ciascuno composto da un massimo di 64 caratteri.

   4. Obbligatorio: indica se è necessario fornire un valore.

4. Per aggiungere campi per un tipo di record, seleziona il tipo di record e scegli Aggiungi campo. Gli attributi comuni sono elencati a scopo di riferimento. Per renderne obbligatorio uno o consentire più valori per questo tipo di record, modificalo immediatamente.

5. Scegli Save changes (Salva modifiche).

Per modificare lo schema come JSON, passa da Form a JSON. Ogni schema, gli attributi comuni o i campi di un tipo di record, è un documento dello schema JSON come quelli dell'esempio.

AWS CLI

Nell'API, gli attributi comuni sono e defaultSchema i campi di ogni tipo di record sono una voce. recordTypeSchemaOverrides Ogni schema è una stringa JSON.

Salva i due schemi dell'esempio come common.json eagent.json, quindi crea il registro:

jq -n --rawfile common common.json --rawfile agent agent.json \
  '{defaultSchema: $common, recordTypeSchemaOverrides: [{recordType: "AGENT", schema: $agent}]}' \
  > schema-config.json

aws agent-registry-control create-registry \
  --name "my-registry" \
  --custom-metadata-schema-configuration file://schema-config.json \
  --region us-east-1

Per modificare lo schema in un secondo momento, modifica i file dello schema, ricostruisci la configurazione e inviala inclusa. optionalValue Questo esempio aggiunge un team campo agli attributi comuni:

jq '.properties.team = {"type": "string"}' common.json > common.tmp && mv common.tmp common.json

jq -n --rawfile common common.json --rawfile agent agent.json \
  '{optionalValue: {defaultSchema: $common, recordTypeSchemaOverrides: [{recordType: "AGENT", schema: $agent}]}}' \
  > schema-update.json

aws agent-registry-control update-registry \
  --registry-id "<registryId>" \
  --custom-metadata-schema-configuration file://schema-update.json \
  --region us-east-1

AWS SDK

import boto3
import json

client = boto3.client('agent-registry-control')

common_attributes = {
    "type": "object",
    "properties": {
        "owner": {"type": "string"},
        "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential"]}
    },
    "required": ["owner"]
}

agent_fields = {
    "type": "object",
    "properties": {
        "modelFamily": {"type": "string"},
        "dataClassification": {
            "type": "string",
            "enum": ["public", "internal", "confidential", "restricted"]
        }
    },
    "required": ["modelFamily", "dataClassification"]
}

response = client.create_registry(
    name='my-registry',
    customMetadataSchemaConfiguration={
        'defaultSchema': json.dumps(common_attributes),
        'recordTypeSchemaOverrides': [
            {'recordType': 'AGENT', 'schema': json.dumps(agent_fields)}
        ]
    }
)
print(f"Registry ARN: {response['registryArn']}")

Per modificare lo schema in un secondo momento, invia la nuova configurazione completa inclusa inoptionalValue:

common_attributes["properties"]["team"] = {"type": "string"}

client.update_registry(
    registryId='<registryId>',
    customMetadataSchemaConfiguration={
        'optionalValue': {
            'defaultSchema': json.dumps(common_attributes),
            'recordTypeSchemaOverrides': [
                {'recordType': 'AGENT', 'schema': json.dumps(agent_fields)}
            ]
        }
    }
)

Cambia lo schema

Un aggiornamento sostituisce l'intero schema, quindi includi tutti i campi e i tipi di record che desideri conservare.

Puoi apportare queste modifiche in qualsiasi momento:

• Aggiungere campi agli attributi comuni o a un tipo di record.

• Aggiungi valori consentiti a un campo Enum. Se ne aggiungi uno a un attributo comune ripetuto da un tipo di record, aggiungilo anche a quel tipo di record, nello stesso aggiornamento.

• Rendi obbligatorio un campo opzionale.

• Sposta un campo da un tipo di record agli attributi comuni, con lo stesso tipo, almeno gli stessi valori consentiti e la stessa impostazione obbligatoria. Il campo si applica quindi a ogni tipo di record e, se è obbligatorio, ogni tipo di record deve avere un valore. Se il tipo di record non contiene campi propri, è possibile rimuoverlo.

Non puoi apportare queste modifiche:

• Assegnare un nuovo nome a un campo.

• Rimuovi un campo. L'unica eccezione è il campo di un tipo di record che si sposta negli attributi comuni.

• Cambia il tipo di campo, ad esempio da Text a Enum.

• Rimuove un valore consentito.

• Rendi facoltativo un campo obbligatorio.

• Rimuovi gli attributi comuni.

• Rimuovi lo schema di metadati personalizzato dal registro. Una volta che un registro ha uno schema, ne mantiene uno.

I record esistenti non vengono modificati quando si aggiorna lo schema. Un record che non corrisponde più, ad esempio perché hai reso obbligatorio un campo, viene segnalato come NON_COMPLIANT in customMetadataSchemaComplianceStatus e mantiene lo stato di approvazione. Aggiorna i metadati personalizzati prima di inviarlo nuovamente per l'approvazione.

Visualizza lo schema

Console: nella pagina dei dettagli del registro, la sezione Schema di metadati personalizzato contiene una scheda per ogni tipo di record con i campi che i record possono contenere.

AWS CLI

aws agent-registry-control get-registry \
  --registry-id "<registryId>" \
  --region us-east-1 \
  --output json | jq '.customMetadataSchemaConfiguration'

AWS SDK

import boto3

client = boto3.client('agent-registry-control')

registry = client.get_registry(registryId='<registryId>')
print(registry['customMetadataSchemaConfiguration'])

Regole e limiti dello schema

• Ogni campo è Text ({"type":"string"}), Enum ({"type":"string","enum":[…​]}), URL ({"type":"string","format":"uri"}) o Boolean (). {"type":"boolean"} I campi non possono essere annidati o utilizzare altre parole chiave, come o. default pattern

• Un campo ha lo stesso tipo di campo (Text, Enum, URL o Boolean) ovunque nello schema. I valori consentiti possono differire in base al tipo di record.

• I nomi dei campi non possono differire solo nelle lettere maiuscole, ad esempio owner eOwner.

• Ogni schema è un oggetto JSON con "type": "object" e almeno un campo all'interno. properties Può anche avererequired, e titledescription, ma non$schema.

• L'requiredelenco di uno schema può denominare solo i campi dello stesso schema. Per richiedere un attributo comune per un tipo di record, ripeti il campo nei campi di quel tipo di record.

La tabella seguente elenca i limiti dello schema.

Limite	Valore
Campi che un tipo di record può contenere, inclusi gli attributi comuni (un campo ripetuto conta una volta)	30
Attributi comuni	30 campi
Numero di valori consentiti per campo Enum	1—25
Lunghezza del valore consentita	64 caratteri
Lunghezza del nome del campo	64 caratteri
Schema title	64 caratteri
Schema description	256 caratteri
Uno schema (gli attributi comuni o i campi di un tipo di record)	16.384 caratteri
Configurazione dell'intero schema	128 KB
Schemi per tipo di record	1

Per i limiti ai valori, vedere Vincoli in Impostare valori di metadati personalizzati su un record.

Informazioni correlate

• Imposta valori di metadati personalizzati su un record

• Cerca record di registro: filtra i risultati in base a valori di metadati personalizzati

• Tipi di record e descrittori supportati

• Crea e gestisci registri