Integração Google Contacts

Visão Geral

Permita que seus agentes gerenciem informações de contatos e diretório através do Google Contacts. Acesse contatos pessoais, pesquise pessoas no diretório, crie e atualize informações de contato, e gerencie grupos de contatos com automação alimentada por IA.

Pré-requisitos

Antes de usar a integração Google Contacts, certifique-se de ter:

Uma conta CrewAI AMP com assinatura ativa
Uma conta Google com acesso ao Google Contacts
Conectado sua conta Google através da página de Integrações

Configurando a Integração Google Contacts

1. Conecte sua Conta Google

Navegue para Integrações CrewAI AMP
Encontre Google Contacts na seção de Integrações de Autenticação
Clique em Conectar e complete o fluxo OAuth
Conceda as permissões necessárias para acesso a contatos e diretório
Copie seu Token Enterprise das Configurações de Integração

2. Instale o Pacote Necessário

uv add crewai-tools

3. Configuração de variável de ambiente

export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"

Ou adicione ao seu arquivo .env:

CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token

Ações Disponíveis

google_contacts/get_contacts

Descrição: Recuperar contatos do usuário do Google Contacts.

Parâmetros:

pageSize (integer, opcional): Número de contatos a retornar (máx 1000). Mínimo: 1, Máximo: 1000
pageToken (string, opcional): O token da página a recuperar.
personFields (string, opcional): Campos a incluir (ex: ‘names,emailAddresses,phoneNumbers’). Padrão: names,emailAddresses,phoneNumbers
requestSyncToken (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false
sortOrder (string, opcional): A ordem na qual as conexões devem ser classificadas. Opções: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING

google_contacts/search_contacts

Descrição: Pesquisar por contatos usando uma string de consulta.

Parâmetros:

query (string, obrigatório): String de consulta de pesquisa
readMask (string, obrigatório): Campos a ler (ex: ‘names,emailAddresses,phoneNumbers’)
pageSize (integer, opcional): Número de resultados a retornar. Mínimo: 1, Máximo: 30
pageToken (string, opcional): Token especificando qual página de resultado retornar.
sources (array, opcional): As fontes para pesquisar. Opções: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. Padrão: READ_SOURCE_TYPE_CONTACT

google_contacts/list_directory_people

Descrição: Listar pessoas no diretório do usuário autenticado.

Parâmetros:

sources (array, obrigatório): Fontes de diretório para pesquisar. Opções: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. Padrão: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
pageSize (integer, opcional): Número de pessoas a retornar. Mínimo: 1, Máximo: 1000
pageToken (string, opcional): Token especificando qual página de resultado retornar.
readMask (string, opcional): Campos a ler (ex: ‘names,emailAddresses’)
requestSyncToken (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false
mergeSources (array, opcional): Dados adicionais para mesclar nas respostas de pessoas do diretório. Opções: CONTACT

google_contacts/search_directory_people

Descrição: Pesquisar por pessoas no diretório.

Parâmetros:

query (string, obrigatório): Consulta de pesquisa
sources (string, obrigatório): Fontes de diretório (use ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’)
pageSize (integer, opcional): Número de resultados a retornar
readMask (string, opcional): Campos a ler

google_contacts/list_other_contacts

Descrição: Listar outros contatos (não nos contatos pessoais do usuário).

Parâmetros:

pageSize (integer, opcional): Número de contatos a retornar. Mínimo: 1, Máximo: 1000
pageToken (string, opcional): Token especificando qual página de resultado retornar.
readMask (string, opcional): Campos a ler
requestSyncToken (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false

google_contacts/search_other_contacts

Descrição: Pesquisar outros contatos.

Parâmetros:

query (string, obrigatório): Consulta de pesquisa
readMask (string, obrigatório): Campos a ler (ex: ‘names,emailAddresses’)
pageSize (integer, opcional): Número de resultados

google_contacts/get_person

Descrição: Obter informações de contato de uma única pessoa por nome do recurso.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso da pessoa a obter (ex: ‘people/c123456789’)
personFields (string, opcional): Campos a incluir (ex: ‘names,emailAddresses,phoneNumbers’). Padrão: names,emailAddresses,phoneNumbers

google_contacts/create_contact

Descrição: Criar um novo contato no catálogo de endereços do usuário.

Parâmetros:

names (array, opcional): Nomes da pessoa. Cada item é um objeto com givenName (string), familyName (string), displayName (string).
emailAddresses (array, opcional): Endereços de email. Cada item é um objeto com value (string, endereço de email) e type (string, ‘home’, ‘work’, ‘other’, padrão ‘other’).
phoneNumbers (array, opcional): Números de telefone. Cada item é um objeto com value (string, número de telefone) e type (string, ‘home’, ‘work’, ‘mobile’, ‘other’, padrão ‘other’).
addresses (array, opcional): Endereços postais. Cada item é um objeto com formattedValue (string, endereço formatado) e type (string, ‘home’, ‘work’, ‘other’, padrão ‘other’).
organizations (array, opcional): Organizações/empresas. Cada item é um objeto com name (string, nome da organização), title (string, cargo) e type (string, ‘work’, ‘other’, padrão ‘work’).

google_contacts/update_contact

Descrição: Atualizar informações de um contato existente.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso da pessoa a atualizar (ex: ‘people/c123456789’).
updatePersonFields (string, obrigatório): Campos a atualizar (ex: ‘names,emailAddresses,phoneNumbers’).
names (array, opcional): Nomes da pessoa. Cada item é um objeto com givenName (string), familyName (string), displayName (string).
emailAddresses (array, opcional): Endereços de email. Cada item é um objeto com value (string, endereço de email) e type (string, ‘home’, ‘work’, ‘other’).
phoneNumbers (array, opcional): Números de telefone. Cada item é um objeto com value (string, número de telefone) e type (string, ‘home’, ‘work’, ‘mobile’, ‘other’).

google_contacts/delete_contact

Descrição: Excluir um contato do catálogo de endereços do usuário.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso da pessoa a excluir (ex: ‘people/c123456789’).

google_contacts/batch_get_people

Descrição: Obter informações sobre várias pessoas em uma única solicitação.

Parâmetros:

resourceNames (array, obrigatório): Nomes de recursos das pessoas a obter (máx 200 itens).
personFields (string, opcional): Campos a incluir (ex: ‘names,emailAddresses,phoneNumbers’). Padrão: names,emailAddresses,phoneNumbers

google_contacts/list_contact_groups

Descrição: Listar os grupos de contatos (rótulos) do usuário.

Parâmetros:

pageSize (integer, opcional): Número de grupos de contatos a retornar. Mínimo: 1, Máximo: 1000
pageToken (string, opcional): Token especificando qual página de resultado retornar.
groupFields (string, opcional): Campos a incluir (ex: ‘name,memberCount,clientData’). Padrão: name,memberCount

google_contacts/get_contact_group

Descrição: Obter um grupo de contatos específico por nome do recurso.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso do grupo de contatos (ex: ‘contactGroups/myContactGroup’).
maxMembers (integer, opcional): Número máximo de membros a incluir. Mínimo: 0, Máximo: 20000
groupFields (string, opcional): Campos a incluir (ex: ‘name,memberCount,clientData’). Padrão: name,memberCount

google_contacts/create_contact_group

Descrição: Criar um novo grupo de contatos (rótulo).

Parâmetros:

name (string, obrigatório): O nome do grupo de contatos.
clientData (array, opcional): Dados específicos do cliente. Cada item é um objeto com key (string) e value (string).

google_contacts/update_contact_group

Descrição: Atualizar informações de um grupo de contatos.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso do grupo de contatos (ex: ‘contactGroups/myContactGroup’).
name (string, obrigatório): O nome do grupo de contatos.
clientData (array, opcional): Dados específicos do cliente. Cada item é um objeto com key (string) e value (string).

google_contacts/delete_contact_group

Descrição: Excluir um grupo de contatos.

Parâmetros:

resourceName (string, obrigatório): O nome do recurso do grupo de contatos a excluir (ex: ‘contactGroups/myContactGroup’).
deleteContacts (boolean, opcional): Se os contatos do grupo também devem ser excluídos. Padrão: false

Exemplos de Uso

Configuração Básica do Agente Google Contacts

from crewai import Agent, Task, Crew

# Crie um agente com capacidades do Google Contacts
contacts_agent = Agent(
    role="Gerenciador de Contatos",
    goal="Gerenciar Google Contacts de forma eficiente",
    backstory="Um assistente IA especializado em gerenciamento e organização de contatos.",
    apps=['google_contacts']  # Todas as ações do Google Contacts estarão disponíveis
)

# Tarefa para criar um novo contato
create_contact_task = Task(
    description="Criar um novo contato chamado 'João Silva' com email '[email protected]' e telefone '11-98765-4321'",
    agent=contacts_agent,
    expected_output="Novo contato criado com sucesso"
)

# Execute a tarefa
crew = Crew(
    agents=[contacts_agent],
    tasks=[create_contact_task]
)

crew.kickoff()

Pesquisando e Listando Contatos

from crewai import Agent, Task, Crew

# Crie um agente focado em pesquisar contatos
search_agent = Agent(
    role="Pesquisador de Contatos",
    goal="Encontrar e recuperar informações de contato",
    backstory="Um assistente IA habilidoso em pesquisar e listar contatos.",
    apps=['google_contacts/search_contacts', 'google_contacts/get_contacts']
)

# Tarefa para pesquisar contatos
search_task = Task(
    description="Pesquisar por contatos chamados 'Maria' e listar seus endereços de email e números de telefone.",
    agent=search_agent,
    expected_output="Lista de contatos correspondentes a 'Maria' com seus detalhes de email e telefone."
)

crew = Crew(
    agents=[search_agent],
    tasks=[search_task]
)

crew.kickoff()

Gerenciando Grupos de Contatos

from crewai import Agent, Task, Crew

# Crie um agente para gerenciar grupos de contatos
group_manager = Agent(
    role="Organizador de Grupos de Contatos",
    goal="Organizar contatos em grupos e gerenciar membros dos grupos",
    backstory="Um assistente IA especializado em criar e gerenciar grupos do Google Contacts.",
    apps=['google_contacts/create_contact_group', 'google_contacts/list_contact_groups']
)

# Tarefa para criar um novo grupo de contatos
create_group_task = Task(
    description="Criar um novo grupo de contatos chamado 'Equipe de Marketing' e listar todos os grupos existentes.",
    agent=group_manager,
    expected_output="Novo grupo de contatos 'Equipe de Marketing' criado e lista de todos os grupos retornada."
)

crew = Crew(
    agents=[group_manager],
    tasks=[create_group_task]
)

crew.kickoff()

Solução de Problemas

Problemas Comuns

Erros de Autenticação

Certifique-se de que sua conta Google tenha as permissões necessárias para acesso a contatos e diretório.
Verifique se a conexão OAuth inclui todos os escopos necessários para a API Google People.

Problemas de Criação/Atualização de Contatos

Certifique-se de que campos obrigatórios como email sejam fornecidos para criação de contatos.
Verifique se o resourceName está correto ao atualizar ou excluir contatos.
Confirme se o formato dos dados para names, emailAddresses, phoneNumbers, etc., corresponde às especificações da API.

Problemas de Pesquisa e Filtro

Certifique-se de que os parâmetros de query e readMask estejam especificados corretamente para search_contacts e search_other_contacts.
Para pesquisas de diretório, certifique-se de que sources esteja definido corretamente (ex: ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’).

Gerenciamento de Grupos de Contatos

Ao criar um grupo de contatos, certifique-se de que o name seja fornecido.
Para get_contact_group, certifique-se de que o resourceName esteja correto.

Obtendo Ajuda

Precisa de Ajuda?

Entre em contato com nossa equipe de suporte para assistência com configuração ou solução de problemas da integração Google Contacts.