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

Note

O papel que ocupas determina quanto da preparação se completa numa única corrida. O Administrador Global pode completar todos os passos de uma só vez. O Administrador do ID do Agente e o Desenvolvedor do ID do Agente podem completar todos os passos, exceto as concessões de permissões do OAuth2 (consentimento do administrador), que exigem ação de um Administrador Global. Quando a configuração está concluída, a CLI imprime os próximos passos para o Administrador Global diretamente na saída.

Syntax

a365 setup [command] [options]

Opções

Option	Description
-?, -h, --help	Mostrar informações de ajuda e utilização.

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. Quando termina, o resultado inclui os próximos passos para um Administrador Global completar as subvenções — incluindo um link direto ou URL de consentimento que possam abrir.

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.

Tip

Se for um Administrador Global e a aplicação cliente conhecida Agent 365 CLI não estiver disponível no seu tenant, setup requirements pede-lhe para a criar automaticamente. Introduza um ID de aplicação existente ou escreva C para criar a aplicação e conceda o consentimento do administrador num único passo – não é necessário registo manual no Entra.

requirements Opções

Option	Description
-v, --verbose	Ativar o registo de verboses.
--category <category>	Faça verificações apenas para uma categoria específica, como Azure, Authentication, PowerShell ou Tenant Enrollment.
-?, -h, --help	Mostrar informações de ajuda e utilização.

Note

setup requirements Não requer um ficheiro de configuração - executa-o em qualquer diretório.

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

Option	Description
-n, --agent-name <name>	Nome da base do agente. Quando fornece esta opção, não precisa de um ficheiro de configuração. O comando deteta automaticamente o ID do inquilino a partir de az account show. Substitui-la com --tenant-id.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Overrides auto-detection. Utilizar com --agent-name.
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
--skip-requirements	Ignorar a verificação de validação dos requisitos. Use com cautela.
--no-endpoint	Não registe o endpoint de mensagens (apenas blueprint).
--endpoint-only	Registar apenas o endpoint de mensagens. Requer um plano já existente.
--update-endpoint <url>	Apague o endpoint de mensagens existente e registe-se um novo com a URL especificada.
--m365	Trate este agente como um agente M365. Regista o endpoint de mensagens através da Plataforma MCP. O padrão é false (opt-in).
-?, -h, --help	Mostrar informações de ajuda e utilização.

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

Option	Description
-?, -h, --help	Mostrar informações de ajuda e utilização.

Subcommands

Subcommand	Description
mcp	Configure concessões OAuth2 do servidor MCP e permissões herdáveis.
bot	Configurar concessões e permissões herdantes da API do bot de mensagens.
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.
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.

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]

This command:

• 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.

Important

• Antes de executar este comando, verifique que aponta deploymentProjectPath para a pasta do projeto que contém o arquivo atualizado ToolingManifest.json. Se o programador adicionar servidores MCP numa máquina diferente, partilhe primeiro a atualização ToolingManifest.json com o Administrador Global. Correr sem o correto ToolingManifest.json não adiciona as novas permissões do servidor MCP ao blueprint.
• Execute este comando depois de o programador executar a365 develop add-mcp-servers. Adicionar servidores MCP ao manifesto e conceder permissões ao blueprint são dois passos separados. Após a conclusão deste comando, as permissões do servidor MCP são visíveis no blueprint do agente.

permissions mcp Opções

Option	Description
-n, --agent-name <name>	Nome da base do agente. Quando fornece esta opção, não precisa de um ficheiro de configuração.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Overrides auto-detection. Utilizar com --agent-name.
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
--remove-legacy-scopes	Remove os escopos partilhados legados (McpServers.*.All formato) do blueprint após a migração para permissões por servidor (Tools.ListInvoke.All). Use apenas depois de confirmar o SDK V2 em funcionamento – os agentes no SDK V1 perdem o acesso à ferramenta se removidos prematuramente.
-?, -h, --help	Mostrar informações de ajuda e utilização.

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

Option	Description
-n, --agent-name <name>	Nome da base do agente. Quando fornece esta opção, não precisa de um ficheiro de configuração.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Overrides auto-detection. Utilizar com --agent-name.
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
-?, -h, --help	Mostrar informações de ajuda e utilização.

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.

a365 setup permissions custom [options]

This command:

• 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

Option	Description
-n, --agent-name <name>	Nome da base do agente. Quando fornece esta opção, não precisa de um ficheiro de configuração.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Overrides auto-detection. Utilizar com --agent-name.
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
--resource-app-id <guid>	ID de aplicação de recurso (GUID) para uma permissão personalizada inline. Utilizar com --scopes.
--scopes <scopes>	Escopos delegados separados por vírgulas para a permissão personalizada inline. Utilizar com --resource-app-id.
-?, -h, --help	Mostrar informações de ajuda e utilização.

Configurar permissões personalizadas em linha

Use --resource-app-id e --scopes para aplicar permissões personalizadas diretamente sem editar a365.config.json:

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

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

O nome do recurso é resolvido automaticamente a partir da Microsoft Entra. Não precisas de o especificar.

Configurar permissões personalizadas através do ficheiro de configuração

Alternativamente, adicione customBlueprintPermissions e a365.config.json execute o comando sem flags inline:

a365 setup permissions custom

Este comando reconcilia o Microsoft Entra com as permissões configuradas – adiciona novas permissões e remove quaisquer permissões que tenha apagado da configuração.

Integração com o 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. Blueprint
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]

This command:

• 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

Option	Description
-n, --agent-name <name>	Nome da base do agente. Quando fornece esta opção, não precisa de um ficheiro de configuração.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Overrides auto-detection. Utilizar com --agent-name.
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
-?, -h, --help	Mostrar informações de ajuda e utilização.

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:

Step	Global Administrator	Administrador de ID de Agente	Desenvolvedor de ID de Agente
Prerequisites check	Yes	Yes	Yes
Criação de blueprint de agente	Yes	Yes	Yes
Permissões herdáveis (apenas para companheiros de equipa de IA)	Yes	Yes	Yes
Concessão de permissão do OAuth2 (consentimento do administrador)	Yes	Exige o passo GA	Exige o passo GA
Concessões de identidade de agente (--authmode s2s ou both)	Yes	Yes	PowerShell fallback

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 na saída para que um Administrador Global complete as concessões OAuth2, incluindo um link direto ou URL de consentimento.

Tip

Se fores Administrador Global, a365 setup all completa tudo numa única execução sem necessidade de transferência.

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 OAuth2 - se não estiver disponível, a CLI imprime os próximos passos no resultado)
• Administrador de ID de Agente, Administrador de Aplicações ou Administrador Global (para concessões de identidade de agente S2S (Servidor-para-Servidor) – --authmode s2s ou both; se não estiver disponível, a CLI imprime um recurso de recurso PowerShell no resumo de configuração)

setup all Opções

Option	Description
-v, --verbose	Mostrar resultados detalhados.
--dry-run	Mostra o que o comando faria sem o executar.
--skip-requirements	Ignorar a verificação de validação dos requisitos. Use com cautela: a configuração pode falhar se os pré-requisitos não forem cumpridos.
--aiteammate	Use este parâmetro para direcionar o fluxo de agentes da equipa de IA para fornecer apenas blueprint e permissões. Sem este parâmetro, o fluxo do agente blueprint cria automaticamente o principal de serviço de identidade do agente sem utilizador Entra. Este parâmetro sobrepõe-se ao aiteammate campo em a365.config.json.
--authmode <mode>	Padrão de autenticação para concessões de permissões de identidade de agente (apenas agentes blueprint). obo (padrão) — subsídios delegados com âmbito de principal, sem necessidade de função administrativa. s2s — atribuições de funções de aplicação no Administrador de Identidade do Agente, requerem Administrador de ID de Agente, Administrador de Aplicações ou Administrador Global; O recurso do PowerShell é impresso se o papel estiver ausente. both — aplica-se a subvenções OBO (On-Behalf-Of) e S2S. Não suportado por --aiteammate. Também pode ser definido como authMode em a365.config.json.
--agent-registration-only	Ignora os passos de blueprint e permissões e só executa o registo do agente. Use para tentar novamente um passo de registo falhado.
--m365	Trate este agente como um agente M365. Regista o endpoint de mensagens através da Plataforma MCP. O padrão é false (opt-in).
-n, --agent-name <name>	Nome da base do agente (por exemplo, "MyAgent"). Quando fornecido, não é necessário qualquer ficheiro de configuração. Deriva nomes de exibição como "<name> Identity" e "<name> Blueprint". O TenantId é detetado automaticamente a partir de az account show (sobrescrito com --tenant-id). O ClientAppId resolve-se ao consultar Agent 365 CLI o seu inquilino.
--tenant-id <tenantId>	ID do inquilino do Azure AD. Anula a deteção automática de az account show. Use com With --agent-name quando estiver a correr num ambiente não interativo ou para direcionar um inquilino específico.
-?, -h, --help	Mostrar informações de ajuda e utilização.

Agent setup

Por defeito, a365 setup all executa o fluxo do agente blueprint. 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.

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

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

Para correr o fluxo de agentes dos colegas de equipa IA, passe --aiteammate.

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).

Note

A configuração do agente requer seis permissões beta adicionais na sua aplicação cliente personalizada: AgentIdentityBlueprint.AddRemoveCreds.All, AgentIdentityBlueprint.DeleteRestore.All, AgentInstance.ReadWrite.All, AgentIdentity.ReadWrite.All, AgentIdentity.Create.All, e AgentIdentity.DeleteRestore.All. Consulte o registo da aplicação cliente personalizada para a lista completa.

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 um Administrador Global, recuse — a CLI mostra os próximos passos para um Administrador Global no resumo de configuração.

Concessões de identidade de agente (--authmode)

Por defeito, a365 setup all cria concessões delegadas com âmbito de principal no principal de serviço de identidade do agente (obo modo). Estas bolsas não exigem um cargo administrativo.

Uso --authmode para controlar o tipo de subsídio:

Value	Behavior	Minimum role
obo (padrão)	Subvenções delegadas com âmbito principal na identidade do agente SP	Nenhum (qualquer utilizador autenticado)
s2s	Atribuições de papéis de aplicação no SP de identidade do agente	Administrador de ID de Agente, Administrador de Aplicações ou Administrador Global
both	Tanto subsídios delegados por OBO como atribuições de funções para aplicações S2S	Papel S2S (acima) para a parte S2S

# Default — OBO delegated grants (no admin role needed)
a365 setup all

# S2S app role assignments
a365 setup all --authmode s2s

# Both OBO and S2S
a365 setup all --authmode both

Quando o utilizador iniciado não tem o papel exigido para bolsas S2S, a CLI imprime um bloco de recurso PowerShell no resumo de configuração. Um administrador pode executá-lo para completar as tarefas.

Defina authModea365.config.json para que se aplique em todas as tentativas sem a bandeira:

{
  "authMode": "s2s"
}

Note

--authmode não é suportado por --aiteammate. Os agentes companheiros de equipa IA usam OBO automaticamente através da identidade do utilizador agente.

Config sync

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

Setting	Written to	Description
Connections.ServiceConnection	appsettings.json / .env	ID do cliente Blueprint, secreto do cliente, ID do tenant e endpoint do token
Agent365Observability	appsettings.json / .env	ID do Agente (Identidade do Agente), ID do blueprint, ID do tenente, ID do cliente e secret do cliente para exportação de telemetria
TokenValidation	appsettings.json	Definições de validação de token (desativadas por defeito para não-DW)
ConnectionsMap	appsettings.json / .env	URL padrão do serviço para o mapeamento de ligação

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-registration-only para tentar novamente apenas esse passo sem repetir o trabalho anterior:

a365 setup all --agent-registration-only