Informazioni di riferimento sulla configurazione

I file di configurazione dell’agente personalizzato sono documenti JSON che definiscono il comportamento di un agente personalizzato. In questa sezione viene fornita una panoramica dei concetti di configurazione e dei modelli comuni.

Informazioni di riferimento sulla configurazione

Per dettagli completi sul formato del file di configurazione dell’agente personalizzato, i campi disponibili e la sintassi, consulta la documentazione supplementare della CLI di Amazon Q Developer:

È anche possibile visualizzare lo schema JSON per i file di configurazione dell’agente personalizzati eseguendo:

/agent schema

Concetti di configurazione

I file di configurazione degli agenti personalizzati contengono diverse sezioni chiave che controllano diversi aspetti del comportamento di questi agenti:

Metadati di base

Ogni agente personalizzato può includere metadati di base per l’identificazione e la documentazione:

Configurazione degli strumenti

La configurazione degli strumenti controlla quali strumenti sono disponibili per l’agente personalizzato e come si comportano:

Impostazioni degli strumenti integrati

Gli strumenti integrati possono essere configurati tramite la sezione toolsSettings per controllarne il comportamento e le autorizzazioni. Ogni strumento supporta opzioni di configurazione specifiche che consentono di approvare preventivamente determinate operazioni o limitare l’accesso a risorse specifiche.

execute_bash tool

Controlla quali comandi bash è possibile eseguire senza la conferma dell’utente:

{
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": ["git status", "git fetch"],
      "deniedCommands": ["git commit .*", "git push .*"],
      "allowReadOnly": true
    }
  }
}

fs_read tool

Controlla quali file e directory è possibile leggere senza la conferma dell’utente:

{
  "toolsSettings": {
    "fs_read": {
      "allowedPaths": ["~/projects", "./src/**"],
      "deniedPaths": ["/some/denied/path/", "/another/denied/path/**/file.txt"]
    }
  }
}

fs_write tool

Controlla su quali file e directory è possibile scrivere senza la conferma dell’utente:

{
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["~/projects/output.txt", "./src/**"],
      "deniedPaths": ["/some/denied/path/", "/another/denied/path/**/file.txt"]
    }
  }
}

use_aws tool

Controlla a quali servizi AWS è possibile accedere senza la conferma dell’utente:

{
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2"],
      "deniedServices": ["eks", "rds"]
    }
  }
}

Autorizzazioni e impostazioni predefinite dello strumento

Gli strumenti integrati presentano diversi comportamenti di autorizzazione predefiniti:

Gli strumenti possono essere esplicitamente consentiti nella sezione allowedTools o configurati con autorizzazioni specifiche tramite toolsSettings. Se uno strumento non è presente nell’elenco allowedTools, agli utenti verrà richiesta l’autorizzazione a meno che non sia impostata una configurazione toolsSettingsappropriata.

Configurazione dei server MCP

La sezione mcpServers definisce a quali server Model Context Protocol può accedere l’agente personalizzato. Ogni configurazione del server include:

Per ulteriori informazioni sull’integrazione MCP, consulta Utilizzo di MCP con Amazon Q Developer.

Risorse e contesto

Gli agenti personalizzati possono includere automaticamente il contesto pertinente attraverso due meccanismi:

Modelli di configurazione comuni

Configurazione dell’agente personalizzata minima

Un semplice agente personalizzato che fornisce operazioni di base sui file con accesso in lettura preapprovato:

{
"name": "basic-ops",
  "description": "Basic file operations custom agent",
  "prompt": "You are a helpful assistant specialized in basic file operations",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash"
  ],
  "allowedTools": [
    "fs_read"
  ]
}

Agente personalizzato per il flusso di lavoro specializzato

Un agente personalizzato configurato per la gestione dell’infrastruttura AWS con autorizzazioni per strumenti specifici:

{
"name": "infra-manage",
  "description": "AWS infrastructure management custom agent",
  "prompt": "You are an expert AWS infrastructure specialist",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws"
  ],
  "allowedTools": [
    "fs_read",
    "use_aws"
  ],
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "cloudformation"]
    }
  },
  "resources": [
    "file://README.md",
    "file://infrastructure/**/*.yaml",
    "file://docs/deployment.md"
  ]
}

Agente personalizzato specifico del progetto con hook

Un agente personalizzato che include il contesto del progetto tramite file statici e comandi dinamici:

{
  "name": "project-dev",
  "description": "Project development custom agent with git context",
  "prompt": "You are a project development assistant with access to git information",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "@git"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status"
  ],
  "resources": [
    "file://README.md",
    "file://CONTRIBUTING.md",
    "file://src/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status --porcelain",
        "timeout_ms": 10000
      }
    ]
  }
}

Agente personalizzato con integrazione del server MCP

Un agente personalizzato che integra strumenti esterni tramite server MCP:

{
"name": "custom-dev",
  "description": "Development custom agent with external tool integration",
  "prompt": "You are a development assistant with access to git and web fetching capabilities",
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": [],
      "timeout": 30000
    },
    "fetch": {
      "command": "fetch-mcp-server",
      "args": ["--timeout", "10"]
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "@git",
    "@fetch/fetch_url"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status",
    "@fetch/fetch_url"
  ],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  }
}