Google 联系人集成

概览

让你的代理通过 Google 联系人管理联系人和目录信息。访问个人联系人、搜索目录人员、创建和更新联系人信息，并借助 AI 驱动的自动化管理联系人分组。

前提条件

在使用 Google 联系人集成前，请确保你已经具备：

一个拥有有效订阅的 CrewAI AMP 账号
一个可访问 Google 联系人的 Google 账号
已通过集成页面连接你的 Google 账号

配置 Google 联系人集成

1. 连接你的 Google 账号

进入 CrewAI AMP Integrations
在身份验证集成部分找到 Google Contacts
点击 Connect 并完成 OAuth 流程
授予联系人和目录访问所需的权限
从 Integration Settings 复制你的 Enterprise Token

2. 安装所需包

uv add crewai-tools

3. 环境变量设置

export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"

或者将其添加到你的 .env 文件中：

CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token

可用操作

google_contacts/get_contacts

描述： 从 Google 联系人检索用户的联系人。

参数：

pageSize (integer, optional): 返回的联系人数量（最大 1000）。最小值：1，最大值：1000
pageToken (string, optional): 要检索的页的令牌。
personFields (string, optional): 要包含的字段（例如：'names,emailAddresses,phoneNumbers'）。默认值：names,emailAddresses,phoneNumbers
requestSyncToken (boolean, optional): 响应是否应包含同步令牌。默认值：false
sortOrder (string, optional): 连接应排序的顺序。可选项：LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING

google_contacts/search_contacts

描述： 使用查询字符串搜索联系人。

参数：

query (string, required): 搜索查询字符串
readMask (string, required): 要读取的字段（例如：'names,emailAddresses,phoneNumbers'）
pageSize (integer, optional): 返回结果数量。最小值：1，最大值：30
pageToken (string, optional): 指定要返回哪个结果页的令牌。
sources (array, optional): 要搜索的来源。可选项：READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE。默认值：READ_SOURCE_TYPE_CONTACT

google_contacts/list_directory_people

描述： 列出已认证用户目录中的人员。

参数：

sources (array, required): 要搜索的目录来源。可选项：DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT。默认值：DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
pageSize (integer, optional): 返回的人员数量。最小值：1，最大值：1000
pageToken (string, optional): 指定要返回哪个结果页的令牌。
readMask (string, optional): 要读取的字段（例如：'names,emailAddresses'）
requestSyncToken (boolean, optional): 响应是否应包含同步令牌。默认值：false
mergeSources (array, optional): 要合并到目录人员响应中的附加数据。可选项：CONTACT

google_contacts/search_directory_people

描述： 搜索目录中的人员。

参数：

query (string, required): 搜索查询
sources (string, required): 目录来源（使用 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE'）
pageSize (string, optional): 返回结果数量
readMask (string, optional): 要读取的字段

google_contacts/list_other_contacts

描述： 列出其他联系人（不在用户个人联系人中的联系人）。

参数：

pageSize (integer, optional): 返回的联系人数量。最小值：1，最大值：1000
pageToken (string, optional): 指定要返回哪个结果页的令牌。
readMask (string, optional): 要读取的字段
requestSyncToken (boolean, optional): 响应是否应包含同步令牌。默认值：false

google_contacts/search_other_contacts

描述： 搜索其他联系人。

参数：

query (string, required): 搜索查询
readMask (string, required): 要读取的字段（例如：'names,emailAddresses'）
pageSize (string, optional): 结果数量

google_contacts/get_person

描述： 通过资源名称获取单个联系人的联系信息。

参数：

resourceName (string, required): 要获取的人员资源名称（例如：'people/c123456789'）
personFields (string, optional): 要包含的字段（例如：'names,emailAddresses,phoneNumbers'）。默认值：names,emailAddresses,phoneNumbers

google_contacts/create_contact

描述： 在用户的地址簿中创建新联系人。

参数：

names (array, optional): 个人姓名

[
  {
    "givenName": "John",
    "familyName": "Doe",
    "displayName": "John Doe"
  }
]

emailAddresses (array, optional): 电子邮件地址

[
  {
    "value": "[email protected]",
    "type": "work"
  }
]

phoneNumbers (array, optional): 电话号码

[
  {
    "value": "+1234567890",
    "type": "mobile"
  }
]

addresses (array, optional): 邮寄地址

[
  {
    "formattedValue": "123 Main St, City, State 12345",
    "type": "home"
  }
]

organizations (array, optional): 组织/公司

[
  {
    "name": "Company Name",
    "title": "Job Title",
    "type": "work"
  }
]

google_contacts/update_contact

描述： 更新现有联系人的信息。

参数：

resourceName (string, required): 要更新的人员资源名称（例如：'people/c123456789'）
updatePersonFields (string, required): 要更新的字段（例如：'names,emailAddresses,phoneNumbers'）
names (array, optional): 个人姓名
emailAddresses (array, optional): 电子邮件地址
phoneNumbers (array, optional): 电话号码

google_contacts/delete_contact

描述： 从用户的地址簿中删除联系人。

参数：

resourceName (string, required): 要删除的人员资源名称（例如：'people/c123456789'）

google_contacts/batch_get_people

描述： 在一次请求中获取多个人员的信息。

参数：

resourceNames (array, required): 要获取的人员资源名称。最大值：200 项
personFields (string, optional): 要包含的字段（例如：'names,emailAddresses,phoneNumbers'）。默认值：names,emailAddresses,phoneNumbers

google_contacts/list_contact_groups

描述： 列出用户的联系人分组（标签）。

参数：

pageSize (integer, optional): 返回的联系人分组数量。最小值：1，最大值：1000
pageToken (string, optional): 指定要返回哪个结果页的令牌。
groupFields (string, optional): 要包含的字段（例如：'name,memberCount,clientData'）。默认值：name,memberCount

google_contacts/get_contact_group

描述： 通过资源名称获取特定联系人分组。

参数：

resourceName (string, required): 联系人分组的资源名称（例如：'contactGroups/myContactGroup'）
maxMembers (integer, optional): 要包含的最大成员数。最小值：0，最大值：20000
groupFields (string, optional): 要包含的字段（例如：'name,memberCount,clientData'）。默认值：name,memberCount

google_contacts/create_contact_group

描述： 创建新的联系人分组（标签）。

参数：

name (string, required): 联系人分组名称

clientData (array, optional): 客户端特定数据

[
  {
    "key": "data_key",
    "value": "data_value"
  }
]

google_contacts/update_contact_group

描述： 更新联系人分组的信息。

参数：

resourceName (string, required): 要更新的联系人分组资源名称（例如：'contactGroups/myContactGroup'）
name (string, required): 联系人分组名称

clientData (array, optional): 客户端特定数据

[
  {
    "key": "data_key",
    "value": "data_value"
  }
]

google_contacts/delete_contact_group

描述： 删除联系人分组。

参数：

resourceName (string, required): 要删除的联系人分组资源名称（例如：'contactGroups/myContactGroup'）
deleteContacts (boolean, optional): 是否同时删除分组中的联系人。默认值：false

使用示例

基础 Google 联系人代理设置

from crewai import Agent, Task, Crew

# Create an agent with Google Contacts capabilities
contacts_agent = Agent(
    role="Contact Manager",
    goal="Manage contacts and directory information efficiently",
    backstory="An AI assistant specialized in contact management and directory operations.",
    apps=['google_contacts']  # All Google Contacts actions will be available
)

# Task to retrieve and organize contacts
contact_management_task = Task(
    description="Retrieve all contacts and organize them by company affiliation",
    agent=contacts_agent,
    expected_output="Contacts retrieved and organized by company with summary report"
)

# Run the task
crew = Crew(
    agents=[contacts_agent],
    tasks=[contact_management_task]
)

crew.kickoff()

目录搜索与管理

from crewai import Agent, Task, Crew

directory_manager = Agent(
    role="Directory Manager",
    goal="Search and manage directory people and contacts",
    backstory="An AI assistant that specializes in directory management and people search.",
    apps=[
        'google_contacts/search_directory_people',
        'google_contacts/list_directory_people',
        'google_contacts/search_contacts'
    ]
)

# Task to search and manage directory
directory_task = Task(
    description="Search for team members in the company directory and create a team contact list",
    agent=directory_manager,
    expected_output="Team directory compiled with contact information"
)

crew = Crew(
    agents=[directory_manager],
    tasks=[directory_task]
)

crew.kickoff()

联系人创建与更新

from crewai import Agent, Task, Crew

contact_curator = Agent(
    role="Contact Curator",
    goal="Create and update contact information systematically",
    backstory="An AI assistant that maintains accurate and up-to-date contact information.",
    apps=['google_contacts']
)

# Task to create and update contacts
curation_task = Task(
    description="""
    1. Search for existing contacts related to new business partners
    2. Create new contacts for partners not in the system
    3. Update existing contact information with latest details
    4. Organize contacts into appropriate groups
    """,
    agent=contact_curator,
    expected_output="Contact database updated with new partners and organized groups"
)

crew = Crew(
    agents=[contact_curator],
    tasks=[curation_task]
)

crew.kickoff()

联系人分组管理

from crewai import Agent, Task, Crew

group_organizer = Agent(
    role="Contact Group Organizer",
    goal="Organize contacts into meaningful groups and categories",
    backstory="An AI assistant that specializes in contact organization and group management.",
    apps=['google_contacts']
)

# Task to organize contact groups
organization_task = Task(
    description="""
    1. List all existing contact groups
    2. Analyze contact distribution across groups
    3. Create new groups for better organization
    4. Move contacts to appropriate groups based on their information
    """,
    agent=group_organizer,
    expected_output="Contacts organized into logical groups with improved structure"
)

crew = Crew(
    agents=[group_organizer],
    tasks=[organization_task]
)

crew.kickoff()

综合联系人管理

from crewai import Agent, Task, Crew

contact_specialist = Agent(
    role="Contact Management Specialist",
    goal="Provide comprehensive contact management across all sources",
    backstory="An AI assistant that handles all aspects of contact management including personal, directory, and other contacts.",
    apps=['google_contacts']
)

# Complex contact management task
comprehensive_task = Task(
    description="""
    1. Retrieve contacts from all sources (personal, directory, other)
    2. Search for duplicate contacts and merge information
    3. Update outdated contact information
    4. Create missing contacts for important stakeholders
    5. Organize contacts into meaningful groups
    6. Generate a comprehensive contact report
    """,
    agent=contact_specialist,
    expected_output="Complete contact management performed with unified contact database and detailed report"
)

crew = Crew(
    agents=[contact_specialist],
    tasks=[comprehensive_task]
)

crew.kickoff()

故障排查

常见问题

权限错误

确保你的 Google 账号具有联系人访问所需的适当权限
验证 OAuth 连接是否包含 Google Contacts API 所需的作用域
检查目录访问权限是否已授予组织联系人

资源名称格式问题

确保资源名称遵循正确格式（例如，联系人使用 'people/c123456789'）
验证联系人分组资源名称是否使用 'contactGroups/groupId' 格式
检查资源名称是否存在且可访问

搜索与查询问题

确保搜索查询格式正确且不为空
为所需数据使用适当的 readMask 字段
验证搜索来源是否指定正确（contacts vs profiles）

联系人创建与更新

创建联系人时确保提供了必填字段
验证电子邮件地址和电话号码格式是否正确
检查 updatePersonFields 参数是否包含所有要更新的字段

目录访问问题

确保你具有访问组织目录所需的权限
验证目录来源是否指定正确
检查你的组织是否允许通过 API 访问目录信息

分页与限制

注意各端点的 page size 限制
对大型结果集使用 pageToken 进行分页
遵守 API 限流并实施适当的延迟

联系人分组与组织

创建新分组时确保分组名称唯一
验证在将联系人加入分组之前它们是否存在
检查你是否有权限修改联系人分组

获取帮助

需要帮助？

如需 Google 联系人集成设置或故障排查方面的帮助，请联系我们的支持团队。