Referência de comando da CLI setup do Agent 365

Configure seu ambiente do Agente 365 com controle granular sobre cada etapa. Esse comando gerencia o fluxo de trabalho de instalação inicial para blueprints do Agente 365.

A funçãoMinimum necessária: Azure Colaborador + O desenvolvedor de IDsagente

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 execute todas as etapas ao mesmo tempo:

# 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 você estiver executando como Administrador de ID do Agente ou Desenvolvedor de ID do Agente (não Administrador Global), a365 setup all concluirá todas as etapas, exceto as concessões de permissão OAuth2. Após a conclusão, um Administrador Global deve concluir as concessõ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 instalação do Agente 365. Executa verificações de requisitos modulares e fornece diretrizes para todos os problemas encontrados.

a365 setup requirements [options]

Este comando executa as seguintes etapas:

• Verifica todos os pré-requisitos necessários para a instalação do Agente 365.
• Relata quaisquer problemas com diretrizes de resolução detalhadas.
• Continua verificando todos os requisitos mesmo se algumas verificações falharem.
• Fornece um resumo de todas as verificações no final.

requirements opções

setup blueprint

Criar blueprint do agente (Entra ID registro de aplicativo).

Permissões mínimas necessárias: função desenvolvedor de ID do agente

a365 setup blueprint [options]

blueprint opções

setup permissions

Configure concessões de permissão OAuth2 e permissões herdáveis.

Permissões mínimas necessárias: Administrador Global

a365 setup permissions [command] [options]

Opções

Subcomandos

setup permissions mcp

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

Permissões mínimas necessárias: Administrador Global

a365 setup permissions mcp [options]

Esse comando:

• Leituras ToolingManifest.json do deploymentProjectPath especificado em a365.config.json.
• Concede concessões de permissão delegada OAuth2 para cada escopo de servidor MCP para o blueprint do agente.
• Configura permissões herdáveis para que as instâncias do agente possam acessar as ferramentas do MCP.
• É idempotente e seguro para ser executado várias vezes.

permissions mcp opções

Migrar para permissões de MCP por servidor

Use --remove-legacy-scopes ao migrar do modelo de permissões compartilhadas herdadas para permissões por servidor:

• Modelo compartilhado herdado: uma ID de aplicativo de recurso único (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) com escopos compartilhados como McpServers.Mail.All e McpServers.Teams.All.
• Modelo por servidor: cada servidor MCP tem sua própria ID de aplicativo com o escopo Tools.ListInvoke.All.

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

setup permissions bot

Configurar concessões da API do Bot de Mensagens OAuth2 e permissões herdáveis.

Permissões mínimas necessárias: Administrador Global

Pré-requisitos: permissões blueprint e 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 agente que vão além das permissões padrão necessárias para a operação do agente. Usando esse comando, você concede ao agente acesso a escopos de Microsoft Graph adicionais, como Presença, Arquivos e Chat, ou a APIs personalizadas registradas no locatário Microsoft Entra ID da sua organização.

Permissões mínimas necessárias: Administrador Global

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

a365 setup permissions custom [options]

Esse comando:

• Configura as concessões de permissão delegada OAuth2 com consentimento do administrador para cada recurso configurado.
• Define permissões herdáveis para que os usuários do agente possam herdar o acesso do blueprint.
• Reconcilia Microsoft Entra com a configuração atual adicionando novas permissões e removendo as permissões que você excluiu da configuração.
• É idempotente e seguro para ser executado várias vezes.

permissions custom opções

Configurar permissões personalizadas

Use a365 config permissions para adicionar permissões personalizadas à 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 instalação, o nome do recurso é resolvido automaticamente de Azure. Você não precisa especificá-lo na configuração.

Remover permissões personalizadas

Para remover permissões personalizadas da configuração e 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 configuração inclui permissões personalizadas, a execução a365 setup all as configura automaticamente como parte de uma única fase de permissão em lote. A ordem de instalação completa é:

1. Projeto
2. Lote de permissões (MCP, API do Bot, permissões de blueprint personalizadas — todas configuradas em conjunto)

setup permissions copilotstudio

Configura concessões de permissão OAuth2 e permissões herdáveis para o blueprint do agente invocar Copilot Studio copilots por meio da API do Power Platform.

Permissões mínimas necessárias: Administrador Global

Pré-requisitos: executar a365 setup blueprint primeiro.

a365 setup permissions copilotstudio [options]

Esse comando:

• Garante que a entidade de serviço da API do Power Platform exista em seu locatário.
• Cria uma concessão de permissão OAuth2 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 Copilot Studio copilots.

permissions copilotstudio opções

Use esse comando quando o agente precisar invocar Copilot Studio copilots em runtime ou chamar APIs do Power Platform que exigem permissões copilotStudio.

setup all

Executar todas as etapas de instalação para configurar o ambiente do Agente 365

a365 setup all [options]

Executa a configuração completa do Agente 365, todas as etapas em sequência.

Inclui: Blueprint e Permissões.

As etapas concluídas dependem da função:

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

1. Conclui todas as etapas que puder (criação de blueprint e permissões herdáveis).
2. Gera URLs de consentimento por administrador por recurso e as salva a365.generated.config.jsonem .
3. Exibe as próximas etapas mostrando como um Administrador Global pode concluir as concessões OAuth2 usando a365 setup admin ou as URLs de consentimento geradas.

Permissões mínimas necessárias:

• Função desenvolvedor de ID do agente (para criação de blueprint)
• Administrador global (para concessões de permissão OAuth2 – se não estiver disponível, use setup admin a entrega)

setup all opções

Configuração do agente

Por padrão, a365 setup all executa o fluxo do agente. Esse fluxo cria um agente sem uma dependência de equipe do Dataverse ou da IA. Ele funciona para agentes que se comunicam diretamente com a plataforma Agent 365 sem a necessidade de uma licença de equipe de IA.

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

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

Em vez disso, para executar o fluxo do companheiro de equipe de IA, passe --aiteammate true.

Esse fluxo executa as seguintes etapas na sequência:

1. Requirements validation — verifica Azure funções e pré-requisitos.
2. A criação doBlueprint — cria ou reutiliza o aplicativo blueprint do agente de Entra ID.
3. Batch permissions — configura concessões de permissão delegadas no blueprint para Microsoft Graph, Ferramentas do Agent 365, API do Bot de Mensagens, API de Observabilidade, Power Platform e quaisquer recursos personalizados.
4. Agent Identity creation — cria uma Identidade do Agente em Entra ID por meio do API do Graph de Identidade do Agente.
5. Registro do agente – registra o agente por meio da API de Registro do Agente Agent V2 do Agent.
6. Sincronização de configuração – grava as configurações de conexão de runtime e a configuração de observabilidade em seus arquivos de projeto (appsettings.json, .env).

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

Se você não tiver um a365.config.json arquivo, use --agent-name para executar a instalação sem um. A CLI detecta automaticamente seu locatário e resolve o aplicativo cliente pesquisando o registro de aplicativo conhecido Agent 365 CLI em seu locatário.

# 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 usar --agent-name:

• TenantId é detectado automaticamente de az account show. Passe --tenant-id para substituir.
• ClientAppId é resolvido procurando um aplicativo Entra nomeado Agent 365 CLI em seu locatário. Se não for encontrada, a CLI sairá com um erro. Consulte o registro personalizado do aplicativo cliente para saber como registrar este aplicativo.
• Os nomes de exibição são derivados como "<name> Agent" (identidade) e "<name> Blueprint" (blueprint).
• A infraestrutura é sempre ignorada (hospedagem externa assumida).
• A sincronização de configuração (gravação appsettings.json) é ignorada, pois não há nenhum caminho de projeto configurado.

Consentimento do administrador durante a instalação

Se o aplicativo cliente não tiver AllPrincipals consentimento do administrador para as permissões necessárias, a CLI detectará isso e solicitará que você conceda consentimento interativamente:

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

Insira y para conceder consentimento na linha. Se você não for um Administrador Global, recuse e use o setup admin fluxo de trabalho de entrega.

Sincronização de configuração

Após uma execução bem-sucedida, a CLI grava automaticamente as configurações de runtime em seus arquivos de projeto:

A CLI criará o arquivo se ele não existir e atualizará campos individuais sem substituir o restante da configuração.

Tentar novamente um registro com falha

Se a instalação concluir o blueprint e as permissões com êxito, mas falhar durante o registro do agente, use --agent-instance-only para tentar novamente apenas essa etapa sem repetir o trabalho anterior:

a365 setup all --agent-instance-only

setup admin

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

Permissões mínimas necessárias: Administrador Global

a365 setup admin [options]

Quando usar setup admin

Use este comando quando:

• Depois que um administrador de ID do agente ou desenvolvedor de ID do agente for executado a365 setup all.
• O resumo da instalação mostra que as concessões do OAuth2 estão pendentes e instrui o Administrador Global a executar esse comando.
• Você deseja executar novamente as concessões de consentimento depois de alterar as permissões na configuração.

Fluxo de trabalho de entrega típico

# 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>"

Esse comando:

• Carrega a configuração do agente do diretório especificado ou do diretório atual por padrão.
• Lê a ID do blueprint do agente e as permissões de recurso configuradas da configuração gerada.
• Cria AllPrincipals concessões de permissão OAuth2 para todos os recursos configurados, incluindo:
  • Microsoft Graph (escopos delegados)
  • Ferramentas do Agente 365 (escopos do servidor MCP)
  • API do Bot de Mensagens
  • API de observabilidade
  • Interface de Programação de Aplicativos Power Platform
  • Todas as permissões personalizadas definidas em sua configuração
• Exibe um prompt de confirmação antes de fazer alterações. Use --yes para ignorar o prompt.

setup admin opções

Alternativa: URL de consentimento

Em vez de executar a365 setup admin, o Administrador Global pode abrir a URL de consentimento combinada que a365 setup all salva em a365.generated.config.json. Essa URL abrange todos os recursos necessários em uma única visita ao navegador.

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