Referência do usuário (versão preliminar)

Note

Este artigo descreve recursos usados em agentes ou fluxos de agentes baseados no harness padrão.

Important

Este é um recurso em versão preliminar.

• Microsoft libera recursos de visualização antes de um lançamento oficial para que os clientes possam obter acesso antecipado e fornecer comentários.
• Os recursos de visualização têm funcionalidade restrita e não são destinados ao uso de produção.
• A Microsoft pode alterar os nomes e os parâmetros das ferramentas MCP em versão prévia. Evite dependências codificadas. A Microsoft mantém suporte a cenários.
• Os recursos de visualização estão sujeitos a Microsoft termos de uso complementares.

Visão geral

ID de servidor	URL no nível do locatário	Nome de exibição	Description
mcp_MeServer	https://agent365.svc.cloud.microsoft/agents/ tenants/{tenantId}/servers/mcp_MeServer	User	Ferramentas para autoconhecimento e consciência organizacional. Use essa ferramenta para acessar perfis de usuário na sua organização e realizar diversas ações, como acessar seu perfil, o perfil de um usuário, o gerente de um usuário ou subordinados diretos.

Ferramentas disponíveis

mcp_graph_getDirectReports

Lista os relatórios diretos de um usuário especificado no diretório. Você deve fornecer o ID do objeto (GUID) do usuário ou seu userPrincipalName UPN (semelhante a um e-mail). Não use me como o userIdentifier.

Parâmetros requeridos:

• IdentificadorUsuário: ID de objeto do usuário (GUID) ou userPrincipalName (UPN)

Note

Não envie me como userIdentifier. Se apenas o nome de exibição estiver disponível, primeiro procure o usuário para obter userPrincipalName, ou o ID do objeto.

Parâmetros opcionais:

• selecionar: Lista separada por vírgulas de propriedades a devolver (por exemplo, id, displayName, mail, jobTitle, userPrincipalName)
• topo: Número de itens a serem devolvidos por página

mcp_graph_getMyManager

Obtém o gerente do usuário conectado (o chamador). Este endpoint sempre retorna o gerente do contexto do usuário atual.

Parâmetros opcionais:

• select: lista separada por vírgulas das propriedades do gerenciador para devolver

mcp_graph_getMyProfile

Recupera os detalhes do perfil do usuário conectado (o chamador). O endpoint sempre retorna o perfil do contexto do usuário atual.

Parâmetros opcionais:

• select: lista separada por vírgulas das propriedades do perfil do usuário
• expandir: Expandir tabelas relacionadas (por exemplo, gerente, directReports)

mcp_graph_getUserProfile

Recupera o perfil de um usuário especificado no diretório. Você deve fornecer o ID do objeto (GUID) do usuário ou seu userPrincipalName UPN (semelhante a um e-mail). Não use me como o userIdentifier. Para o usuário conectado, use mcp_graph_getMyProfile.

Parâmetros requeridos:

• IdentificadorUsuário: ID de objeto do usuário (GUID) ou userPrincipalName (UPN)

Note

Não me envie. Se apenas o nome de exibição estiver disponível, primeiro procure o usuário.

Parâmetros opcionais:

• select: lista separada por vírgulas das propriedades do usuário para devolver
• expandir: Expandir uma tabela relacionada (gerente OU directReports). Você pode expandir apenas uma propriedade por pedido.

mcp_graph_getUsersManager

Recupera o gerente de um usuário especificado no diretório. Forneça o ID do objeto (GUID) do usuário ou o userPrincipalName dele (UPN semelhante a um email). Não use me como o userIdentifier. Para o usuário conectado, use mcp_graph_getMyManager.

Parâmetros requeridos:

• IdentificadorUsuário: ID de objeto do usuário (GUID) ou userPrincipalName (UPN)

Note

Não me envie. Se apenas o nome de exibição estiver disponível, primeiro procure o usuário.

Parâmetros opcionais:

• Selecione: Lista separada por vírgulas de propriedades a serem retornadas para o gerente, comoid, , displayName, mail, , jobTitleuserPrincipalName

mcp_graph_listUsers

Recupera uma lista de usuários na organização. Dá suporte a opções de consulta como $select, , $filter, $top, $orderby. O padrão ConsistencyLevel é eventual.

Parâmetros opcionais:

• Topo: Mostrar somente os primeiros n utilizadores
• select: lista separada por vírgulas das propriedades do usuário para devolver
• Filtrar: Filtrar usuários por propriedade, como startswith(displayName,'A')
• orderby: Ordenar resultados por determinada propriedade, como displayName
• busca: Busca em texto livre para usuários. Formato: "property:value", como displayName:Neha para pesquisar nomes de exibição que contêm Neha. Suporta múltiplas propriedades com espaços. Regra de fallback: se $search falhar ou não retornar resultados, tente novamente automaticamente com $filter.
• Contagem: Incluir contagem de itens (true ou false)
• ConsistencyLevel: Cabeçalho necessário para consultas avançadas (padrão: eventual)

Principais recursos

Autoconhecimento

• Obtenha o perfil do usuário conectado.
• Obtenha o gestor do usuário autenticado.
• Acesse as informações de contexto do usuário atual.
• Não há necessidade de identificadores de usuário.

Perfis de usuário

• Recupere o perfil de qualquer usuário por ID ou UPN.
• Acesse propriedades do usuário, como displayName, maile jobTitlemuito mais.
• Expanda tabelas relacionadas, como manager e directReports.
• Selecione propriedades usando $select.

Hierarquia organizacional

• Obtenha o supervisor de um usuário.
• Obtenha relatórios diretos do usuário.
• Navegue pela estrutura de relatórios.
• Relações entre gerente e subordinado direto.

Identificação do usuário

• Liste os usuários da organização.
• Pesquisa em texto livre com alternativa automática.
• Filtragem e ordenação do OData.
• Suporte à paginação.
• Contar usuários nos resultados.

Capacidades de consulta

• OData $select para seleção de propriedades.
• O OData $filter para filtragem de usuário.
• O OData $expand para entidades relacionadas.
• O OData $orderby para classificação.
• $search de texto livre com alternativa.
• Suporte de consistência eventual.

Observações

• Use mcp_graph_getMyProfile para o usuário conectado, não mcp_graph_getUserProfile com mim.
• Use mcp_graph_getMyManager para o gerenciador do usuário logado.
• userIdentifier deve ser ID de objeto (GUID) ou userPrincipalName (UPN), não use nome de exibição.
• Se apenas o nome de exibição estiver disponível, use mcp_graph_listUsers para localizar o usuário primeiro.
• $expand só pode expandir uma propriedade por solicitação (manager ou directReports).
• $search tem fallback automático para $filter se a busca falhar.
• ConsistencyLevel eventual necessário para consultas avançadas.
• Formato de pesquisa: "property:value" com aspas.

Casos de uso comuns

Obter minhas informações

• Use mcp_graph_getMyProfile para acessar o perfil do usuário atual.
• Use mcp_graph_getMyManager para obter o gerente do usuário atual.

Localizar um usuário

• Use mcp_graph_listUsers com o parâmetro de busca.

  Exemplo: search='"displayName:John"' para localizar usuários chamados John.

• Obter userPrincipalName ou ID de objeto nos resultados.

Obter detalhes do usuário

• Usar o mcp_graph_getUserProfile com o userIdentifier.
• Use select para obter propriedades específicas.
• Use expand para incluir manager ou directReports.

Obter estrutura organizacional

• Use mcp_graph_getUsersManager para obter o gerente do usuário.
• Use mcp_graph_getDirectReports para obter os relatórios diretos de um usuário.
• Chamadas em cadeia para navegar na hierarquia de relatórios.