Referência da configuração - Amazon Q Developer
Referência da configuraçãoConceitos de configuraçãoPadrões de configuração comuns

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Referência da configuração

Os arquivos de configuração de agentes personalizados são documentos JSON que definem como um agente personalizado se comporta. Esta seção fornece uma visão geral dos conceitos de configuração e padrões comuns.

Referência da configuração

Para obter detalhes completos sobre o formato personalizado do arquivo de configuração do agente, os campos disponíveis e a sintaxe, consulte a documentação complementar da Amazon Q Developer CLI:

Você também pode visualizar o esquema JSON para arquivos de configuração de agentes personalizados executando:

/agent schema

Conceitos de configuração

Os arquivos de configuração do agente personalizado contêm várias seções principais que controlam diferentes aspectos do comportamento do agente personalizado:

Metadados básicos

Cada agente personalizado pode incluir metadados básicos para identificação e documentação:

  • Nome - O identificador do agente personalizado (derivado do nome do arquivo, se não for especificado)

  • Descrição - Explicação legível por humanos da finalidade do agente personalizado

Configuração de ferramentas

A configuração das ferramentas controla quais ferramentas estão disponíveis para o agente personalizado e como elas se comportam:

ferramentas

Lista todas as ferramentas que o agente personalizado pode potencialmente usar, incluindo ferramentas integradas e ferramentas de servidor MCP

Ferramentas permitidas

Especifica quais ferramentas podem ser executadas sem a confirmação do usuário, melhorando a eficiência do fluxo de trabalho

Aliases de ferramentas

Fornece nomes alternativos para ferramentas, úteis para resolver conflitos de nomenclatura ou criar atalhos

Configurações de ferramentas

Configura o comportamento específico para ferramentas individuais, como caminhos de arquivo permitidos ou permissões de serviço

Configuração de servidores MCP

A mcpServers seção define quais servidores do Model Context Protocol o agente personalizado pode acessar. Cada configuração de servidor inclui:

  • Comando - O comando executável para iniciar o servidor MCP

  • Argumentos - argumentos de linha de comando para o servidor

  • Variáveis de ambiente - Configurações de ambiente para o processo do servidor

  • Configurações de tempo limite - Solicitar configuração de tempo limite

Para obter mais informações sobre a integração do MCP, consulte Usando o MCP com o Amazon Q Developer.

Recursos e contexto

Agentes personalizados podem incluir automaticamente o contexto relevante por meio de dois mecanismos:

recursos

Arquivos e diretórios a serem incluídos no contexto do agente personalizado, oferecendo suporte a padrões globais para seleção flexível de arquivos

hooks

Comandos a serem executados em pontos de gatilho específicos (como inicialização personalizada do agente ou entrada do usuário), com saída incluída no contexto

Padrões de configuração comuns

Configuração mínima personalizada do agente

Um agente personalizado simples que fornece operações básicas de arquivos com acesso de leitura pré-aprovado:

{
"name": "basic-ops",
  "description": "Basic file operations custom agent",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash"
  ],
  "allowedTools": [
    "fs_read"
  ]
}

Agente personalizado de fluxo de trabalho especializado

Um agente personalizado configurado para o gerenciamento da infraestrutura da AWS com permissões de ferramentas específicas:

{
"name": "infra-manage",
  "description": "AWS infrastructure management custom agent",
  "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 do projeto com ganchos

Um agente personalizado que inclui o contexto do projeto por meio de arquivos estáticos e comandos dinâmicos:

{
  "name": "project-dev",
  "description": "Project development custom agent with git context",
  "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 com integração de servidor MCP

Um agente personalizado que integra ferramentas externas por meio de servidores MCP:

{
"name": "custom-dev",
  "description": "Development custom agent with external tool integration",
  "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"
  }
}