Referencia de la configuración Conceptos de configuración Patrones de configuración frecuentes

Referencia de la configuración

Los archivos de configuración de los agentes personalizados son documentos de JSON que definen cómo se comporta un agente personalizado. En esta sección se proporciona información general sobre los conceptos de configuración y los patrones habituales.

Referencia de la configuración

Para obtener la información completa sobre el formato de los archivos de configuración de los agentes personalizados, los campos disponibles y la sintaxis, consulte la documentación complementaria de la CLI de Amazon Q Developer:

Formato de configuración de los agentes: referencia completa para todas las opciones de configuración.
Referencia sobre las herramientas integradas: documentación sobre todas las herramientas integradas y sus opciones de configuración.

También puede ver el esquema de JSON de los archivos de configuración de los agentes personalizados. Para ello, debe ejecutar:

/agent schema

Conceptos de configuración

Los archivos de configuración de los agentes personalizados incluyen varias secciones clave que controlan distintos aspectos del comportamiento de los agentes personalizados:

Metadatos básicos

Cada agente personalizado puede incluir metadatos básicos para la identificación y la documentación:

Nombre: el identificador del agente personalizado (derivado del nombre del archivo si no se especifica).
Descripción: explicación en lenguaje natural del objetivo del agente personalizado.
Mensaje: contexto de alto nivel para el agente, similar a una petición del sistema.

Configuración de herramientas

La configuración de las herramientas controla las herramientas que están disponibles para el agente personalizado y cómo se comportan:

herramientas: Enumera todas las herramientas que el agente personalizado puede utilizar, incluidas las herramientas integradas y las herramientas del servidor MCP.
allowedTools: Especifica qué herramientas se pueden ejecutar sin la confirmación del usuario, lo que mejora la eficacia del flujo de trabajo.
toolAliases: Proporciona nombres alternativos para las herramientas, útiles para resolver conflictos de nomenclatura o crear atajos.
toolsSettings: Configura el comportamiento específico de las herramientas individuales, como, por ejemplo, las rutas de archivo permitidas o los permisos de servicio.

Configuración de herramientas integradas

Las herramientas integradas se pueden configurar a través de la sección toolsSettingspara controlar su comportamiento y permisos. Cada herramienta admite opciones de configuración específicas que permiten aprobar previamente determinadas operaciones o restringir el acceso a determinados recursos.

Herramienta execute_bash

Controla los comandos bash que se pueden ejecutar sin la confirmación del usuario:


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

allowedCommands: Se permite un conjunto de comandos específicos sin pedir confirmación. Admite el formato de expresiones regulares con los anclajes \A y \z.
deniedCommands: Conjunto de comandos para denegar. Admite el formato de expresiones regulares. Las reglas de denegación se evalúan antes que las reglas de permiso.
allowReadOnly: Booleano (valor predeterminado: true): indica si se permiten comandos de solo lectura sin pedir confirmación.

Herramienta fs_read

Controla los archivos y directorios que se pueden leer sin la confirmación del usuario:


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

allowedPaths: Conjunto de rutas que se pueden leer sin pedir confirmación. Admite los patrones globales con un comportamiento similar al de gitignore.
deniedPaths: Conjunto de rutas para denegar el acceso. Admite los patrones globales. Las reglas de denegación se evalúan antes que las reglas de permiso.

Herramienta fs_write

Controla los archivos y directorios en los que se pueden escribir sin la confirmación del usuario:


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

allowedPaths: Conjunto de rutas en las que se pueden escribir sin pedir confirmación. Admite los patrones globales con un comportamiento similar al de gitignore.
deniedPaths: Conjunto de rutas para denegar el acceso de escritura. Admite los patrones globales. Las reglas de denegación se evalúan antes que las reglas de permiso.

Herramienta use_aws

Controla los servicios de AWS a los que se pueden acceder sin la confirmación del usuario:


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

allowedServices: Conjunto de servicios de AWS a los que se pueden acceder sin pedir confirmación.
deniedServices: Conjunto de servicios de AWS para denegar el acceso. Las reglas de denegación se evalúan antes que las reglas de permiso.

Permisos y valores predeterminados de las herramientas

Las herramientas integradas cuentan con diferentes comportamientos de permisos predeterminados:

De forma predeterminada, son de confianza: fs_read y report_issue.
De forma predeterminada, requieren permiso: execute_bash, fs_write y use_aws.
Sin opciones de configuración: introspect, knowledge, thinking y todo_list.

Las herramientas se pueden permitir explícitamente en la sección allowedTools o se pueden configurar con permisos específicos a través de toolsSettings. Si una herramienta no está en la lista de allowedTools, se solicitará permiso a los usuarios, a menos que se establezca una configuración de toolsSettings adecuada.

Configuración del servidor MCP

La sección mcpServers define a qué servidores del Protocolo de contexto para modelos (MCP) puede acceder el agente personalizado. La configuración de cada servidor incluye:

Comando: el comando ejecutable para iniciar el servidor MCP.
Argumentos: los argumentos de la línea de comandos para el servidor.
Variables de entorno: configuración del entorno para el proceso del servidor.
Configuración del tiempo de espera: configuración del tiempo de espera de la solicitud.

Para obtener más información sobre la integración de MCP, consulte Using MCP with Amazon Q Developer.

Recursos y contexto

Los agentes personalizados pueden incluir automáticamente el contexto pertinente a través de dos mecanismos:

recursos: Archivos y directorios para incluir en el contexto del agente personalizado, admitiendo los patrones globales para una selección flexible de archivos.
enlaces: Comandos para ejecutar en puntos de activación específicos (como el inicio del agente personalizado o entrada de usuario), con el resultado incluido en el contexto.

Patrones de configuración frecuentes

Configuración mínima de agentes personalizados

Un agente personalizado sencillo que proporciona operaciones básicas de archivos con acceso de lectura aprobado previamente:


{
"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 personalizado de flujo de trabajo especializado

Un agente personalizado configurado para la administración de la infraestructura de AWS con permisos específicos de herramientas:


{
"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 personalizado específico del proyecto con enlaces

Un agente personalizado que incluye el contexto del proyecto a través de archivos estáticos y comandos dinámicos:


{
  "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 personalizado con integración de servidor MCP

Un agente personalizado que integra herramientas externas a través de servidores 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"
  }
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Administración de los agentes personalizados

Ejemplos