> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração Google Contacts

> Gerenciamento de contatos e diretório com integração Google Contacts para CrewAI.

## 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](https://app.crewai.com) com assinatura ativa
* Uma conta Google com acesso ao Google Contacts
* Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)

## Configurando a Integração Google Contacts

### 1. Conecte sua Conta Google

1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Google Contacts** na seção de Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para acesso a contatos e diretório
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Instale o Pacote Necessário

```bash theme={null}
uv add crewai-tools
```

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

<Note>
  Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
  ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
</Note>

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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').
  </Accordion>

  <Accordion title="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').
  </Accordion>

  <Accordion title="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').
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Exemplos de Uso

### Configuração Básica do Agente Google Contacts

```python theme={null}
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 'joao.silva@exemplo.com' 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

```python theme={null}
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

```python theme={null}
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

<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
  Entre em contato com nossa equipe de suporte para assistência com configuração
  ou solução de problemas da integração Google Contacts.
</Card>