Referência de comando CLI setup do Agente 365

Configura o teu ambiente Agent 365 com controlo granular em cada etapa. Este comando gere o fluxo de trabalho inicial de configuração dos blueprints do Agente 365.

Papel mínimo exigido: Azure Contribuidor + Desenvolvedor ID de Agente

Sintaxe

a365 setup [command] [options]

Opções

Ordem de execução recomendada

# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create blueprint
a365 setup blueprint

# 2. Configure MCP permissions
a365 setup permissions mcp

# 3. Configure bot permissions
a365 setup permissions bot

# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 5. Configure custom permissions (if needed)
a365 setup permissions custom

Ou executar todos os passos de uma vez:

# Full setup using config file (a365.config.json)
a365 setup all

# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"

Se estiver a correr como Administrador de ID de Agente ou Desenvolvedor de ID de Agente (não Administrador Global), a365 setup all completa todos os passos exceto a concessão de permissões do OAuth2. Após a conclusão, um Administrador Global deve concluir as subvenções:

# Non-admin path: run setup, then hand off to Global Administrator
a365 setup all

# Global Administrator completes OAuth2 grants
a365 setup admin --config-dir "<path-to-config-folder>"

setup requirements

Valide os pré-requisitos para a configuração do Agent 365. Executa verificações modulares de requisitos e fornece orientações para quaisquer problemas que encontre.

a365 setup requirements [options]

Este comando executa os seguintes passos:

• Verifica todos os pré-requisitos necessários para a configuração do Agente 365.
• Reporta quaisquer problemas com orientações detalhadas de resolução.
• Continua a verificar todos os requisitos mesmo que algumas verificações falhem.
• Fornece um resumo de todas as verificações no final.

requirements Opções

setup blueprint

Criar um plano de agente (registo de candidatura Entra ID).

Permissões mínimas obrigatórias: ID de agente Função de programador

a365 setup blueprint [options]

blueprint Opções

setup permissions

Configure concessões de permissões e permissões hereditárias do OAuth2.

Permissões mínimas obrigatórias: Administrador Global

a365 setup permissions [command] [options]

Opções

Subcommands

setup permissions mcp

Configure concessões OAuth2 do servidor MCP e permissões herdáveis.

Permissões mínimas obrigatórias: Administrador Global

a365 setup permissions mcp [options]

Este comando:

• Lê ToolingManifest.json a partir do deploymentProjectPath especificado em a365.config.json.
• Concede concessões de permissões delegadas ao OAuth2 para cada âmbito de servidor MCP ao blueprint do agente.
• Configura permissões herdadas para que as instâncias do agente possam aceder às ferramentas MCP.
• É idempotente e seguro para usar várias vezes.

permissions mcp Opções

Migrar para permissões MCP por servidor

Utilização --remove-legacy-scopes ao migrar do modelo de permissões partilhadas legado para permissões por servidor:

• Modelo partilhado legado: Um único ID de aplicação de recurso (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) com escopos partilhados como McpServers.Mail.All e McpServers.Teams.All.
• Modelo por servidor: Cada servidor MCP tem o seu próprio ID de aplicação com o âmbito Tools.ListInvoke.All.

O exemplo seguinte mostra como as permissões por servidor aparecem no centro de administração Microsoft Entra após a aplicação do blueprint. Cada servidor MCP, como o Work IQ Calendar MCP e o Work IQ Mail MCP, tem o seu próprio âmbito delegado Tools.ListInvoke.All . Um âmbito partilhado McpServersMetadata.Read.All fornece acesso aos metadados do servidor MCP.

setup permissions bot

Configurar concessões e permissões herdantes da API do bot de mensagens.

Permissões mínimas obrigatórias: Administrador Global

Pré-requisitos: Blueprint e permissões MCP (executar a365 setup permissions mcp primeiro)

a365 setup permissions bot [options]

permissions bot Opções

setup permissions custom

Aplica permissões de API personalizadas ao blueprint do seu agente que vão além das permissões padrão exigidas para a operação do agente. Ao usar este comando, concede ao seu agente acesso a escopos adicionais do Microsoft Graph, como Presença, Ficheiros e Chat, ou a APIs personalizadas registadas no inquilino Microsoft Entra ID da sua organização.

Permissões mínimas obrigatórias: Administrador Global

Pré-requisitos: Corre a365 setup blueprint primeiro. Adicione permissões personalizadas antes a365.config.jsona365 config permissions de executar este comando.

a365 setup permissions custom [options]

Este comando:

• Configura concessões de permissões delegadas OAuth2 com consentimento do administrador para cada recurso configurado.
• Define permissões herdáveis para que os utilizadores agentes possam herdar o acesso do blueprint.
• Reconcilia o Microsoft Entra com a configuração atual adicionando novas permissões e removendo quaisquer permissões que tenha apagado da configuração.
• É idempotente e seguro para usar várias vezes.

permissions custom Opções

Configurar permissões personalizadas

Use a365 config permissions para adicionar permissões personalizadas à sua configuração antes de executar este comando:

# Add Microsoft Graph extended permissions
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 config permissions `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

# Apply all configured custom permissions
a365 setup permissions custom

Durante a configuração, o nome do recurso é resolvido automaticamente a partir do Azure. Não precisas de especificar isso na configuração.

Remover permissões personalizadas

Para remover permissões personalizadas tanto da configuração como do Microsoft Entra:

# Step 1: Remove from config
a365 config permissions --reset

# Step 2: Reconcile Microsoft Entra with updated config
a365 setup permissions custom

Integração com setup all

Quando a sua configuração inclui permissões personalizadas, a execução a365 setup all configura-as automaticamente como parte de uma única fase de permissões por lote. A ordem completa de configuração é:

1. Modelo
2. Batch de permissões (MCP, API de bots, permissões de blueprint personalizado — todas configuradas em conjunto)

setup permissions copilotstudio

Configura concessões de permissões OAuth2 e permissões herdadas para o blueprint do agente invocar copilots do Copilot Studio através da API do Power Platform.

Permissões mínimas obrigatórias: Administrador Global

Pré-requisitos: Corre a365 setup blueprint primeiro.

a365 setup permissions copilotstudio [options]

Este comando:

• Garante que o principal do serviço API da Power Platform existe no seu tenant.
• Cria uma concessão de permissões OAuth2 a partir do blueprint para a API do Power Platform com o CopilotStudio.Copilots.Invoke escopo.
• Define permissões herdáveis para que as instâncias do agente possam invocar copilotos do Copilot Studio.

permissions copilotstudio Opções

Use este comando quando o seu agente precisar de invocar copilots do Copilot Studio em tempo de execução ou chamar APIs do Power Platform que exijam permissões do CopilotStudio.

setup all

Execute todos os passos de configuração para configurar o seu ambiente Agent 365

a365 setup all [options]

Executa toda a configuração do Agent 365, todos os passos em sequência.

Inclui: Plano e Permissões.

Os passos que se completam dependem do seu papel:

Quando executa a365 setup all sem o Administrador Global, a CLI:

1. Completa todos os passos possíveis (criação de blueprints e permissões herdárias).
2. Gera URLs de consentimento de administrador por recurso e guarda-as em a365.generated.config.json.
3. Apresenta os próximos passos que mostram como um Administrador Global pode completar as concessões OAuth2 usando qualquer a365 setup admin uma das URLs de consentimento geradas.

Permissões mínimas necessárias:

• Função de Desenvolvedor de ID de Agente (para criação de blueprint)
• Administrador Global (para concessões de permissões do OAuth2 - se não estiver disponível, use setup admin handoff)

setup all Opções

Configuração do agente

Por defeito, a365 setup all executa o fluxo de agentes. Este fluxo cria um agente sem dependência do Dataverse ou da IA dos colegas de equipa. Funciona para agentes que comunicam diretamente com a plataforma Agent 365 sem exigir uma licença de colega de equipa com IA.

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

Para executar o fluxo de colegas de equipa da IA, passa --aiteammate true.

Este fluxo executa os seguintes passos em sequência:

1. Validação de requisitos — verifica Azure funções e pré-requisitos.
2. Blueprint creation — cria ou reutiliza a aplicação Entra ID Agent Blueprint.
3. lote — configura concessões de permissões delegadas no blueprint para Microsoft Graph, Agent 365 Tools, API de Bots de Mensagens, API de Observabilidade, Power Platform e quaisquer recursos personalizados.
4. Criação de Identidade de Agente — cria uma Identidade de Agente em Entra ID através do Graph API de Identidade de Agente.
5. Registo de agente — regista o agente através da API de Registo de Agentes AgentX V2.
6. Sincronização de configuração — escreve as definições de ligação em tempo de execução e a configuração de observabilidade nos ficheiros do seu projeto (appsettings.json, .env).

Configuração sem configuração com --agent-name

Se não tens ficheiro a365.config.json , usa --agent-name para correr a configuração sem um. A CLI deteta automaticamente o seu inquilino e resolve a aplicação cliente ao consultar o registo Agent 365 CLI conhecido da aplicação no seu inquilino.

# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run

# Run the full setup
a365 setup all --agent-name "MyAgent"

Ao utilizar --agent-name:

• O TenantId é detetado automaticamente a partir de az account show. Passe --tenant-id para sobreposição.
• O ClientAppId resolve-se procurando uma aplicação Entra nomeada Agent 365 CLI no seu inquilino. Se não for encontrado, a CLI sai com um erro. Consulte Registo personalizado de aplicação cliente para saber como registar esta aplicação.
• Os nomes de exibição são derivados como "<name> Agent" (identidade) e "<name> Blueprint" (blueprint).
• A infraestrutura é sempre ignorada (assumindo-se alojamento externo).
• A sincronização de configuração (escrita appsettings.json) é ignorada porque não há caminho de projeto configurado.

Consentimento do administrador durante a configuração

Se a sua aplicação cliente não tiver AllPrincipals consentimento de administrador para as permissões necessárias, a CLI deteta isso e pede-lhe para conceder consentimento de forma interativa:

The following permissions require admin consent:
  AgentIdentity.ReadWrite.All
  AgentIdentity.Create.All
  ...
Grant admin consent for these permissions now? [y/N]:

Participe y para conceder consentimento em linha. Se não for Administrador Global, recuse e use o setup admin fluxo de trabalho de handoff.

Sincronização de configuração

Após uma execução bem-sucedida, a CLI escreve automaticamente as definições de execução nos ficheiros do seu projeto:

A CLI cria o ficheiro se este não existir e atualiza os campos individuais sem sobrescrever o resto da tua configuração.

Retentar um registo falhado

Se a configuração concluir com sucesso o blueprint e as permissões mas falhar durante o registo do agente, use --agent-instance-only para tentar novamente apenas esse passo sem repetir o trabalho anterior:

a365 setup all --agent-instance-only

setup admin

Completa as concessões de permissões do OAuth2 (consentimento do administrador) que exigem Administrador Global. Execute este comando depois de um Administrador de ID de Agente ou Desenvolvedor de ID de Agente executar a365 setup all.

Permissões mínimas obrigatórias: Administrador Global

a365 setup admin [options]

Quando usar setup admin

Use este comando quando:

• Depois de um Administrador de ID de Agente ou Desenvolvedor de ID de Agente executar a365 setup all.
• O resumo de configuração mostra que as bolsas OAuth2 estão pendentes e instrui o Administrador Global a executar este comando.
• Deves voltar a executar as concessões de consentimento depois de mudares as permissões na configuração.

Fluxo de trabalho típico de handoff

# Step 1: Agent ID Admin or Developer runs setup
a365 setup all

# The CLI displays next steps, for example:
# "ACTION REQUIRED — Global Administrator must complete OAuth2 grants"
# "Option 1: a365 setup admin --config-dir '<path-to-config-folder>'"
# "Option 2: Share the consent URL displayed above with your Global Administrator"

# Step 2: Agent ID Admin shares config folder with Global Administrator
# (contains a365.config.json and a365.generated.config.json)

# Step 3: Global Administrator completes the grants
a365 setup admin --config-dir "<path-to-config-folder>"

Este comando:

• Carrega a configuração do agente a partir do diretório especificado ou do diretório atual por defeito.
• Lê o ID do blueprint do agente e as permissões de recursos configuradas a partir da configuração gerada.
• Cria AllPrincipals concessões de permissões OAuth2 para todos os recursos configurados, incluindo:
  • Microsoft Graph (escopos delegados)
  • Ferramentas Agent 365 (escopos do servidor MCP)
  • API de bots de mensagens
  • API de observabilidade
  • API da Plataforma de Energia
  • Quaisquer permissões personalizadas definidas na tua configuração
• Mostra um prompt de confirmação antes de fazer alterações. Usa --yes para contornar o enunciado.

setup admin Opções

Alternativa: URL de consentimento

Em vez de executar a365 setup admin, o Administrador Global pode abrir o URL de consentimento combinado que a365 setup all guarda em a365.generated.config.json. Este URL cobre todos os recursos necessários numa única visita ao navegador.

# Display the generated config to find the consent URL
a365 config display -g
# Look for: combinedAdminConsentUrl