Google Contacts 통합

개요

에이전트가 Google Contacts를 통해 연락처와 디렉토리 정보를 관리할 수 있도록 합니다. 개인 연락처에 액세스하고, 디렉토리 사람들을 검색하고, 연락처 정보를 생성 및 업데이트하고, AI 기반 자동화로 연락처 그룹을 관리합니다.

전제 조건

Google Contacts 통합을 사용하기 전에 다음 사항을 확인하세요:

활성 구독이 있는 CrewAI AMP 계정
Google Contacts 액세스 권한이 있는 Google 계정
통합 페이지를 통해 Google 계정 연결

Google Contacts 통합 설정

1. Google 계정 연결

CrewAI AMP 통합으로 이동
인증 통합 섹션에서 Google Contacts 찾기
연결을 클릭하고 OAuth 플로우 완료
연락처 및 디렉토리 액세스에 필요한 권한 부여
통합 설정에서 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 Contacts에서 사용자의 연락처를 검색합니다.

매개변수:

pageSize (integer, 선택사항): 반환할 연락처 수 (최대 1000). 최소: 1, 최대: 1000
pageToken (string, 선택사항): 검색할 페이지의 토큰.
personFields (string, 선택사항): 포함할 필드 (예: ‘names,emailAddresses,phoneNumbers’). 기본값: names,emailAddresses,phoneNumbers
requestSyncToken (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false
sortOrder (string, 선택사항): 연결을 정렬할 순서. 옵션: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING

google_contacts/search_contacts

설명: 쿼리 문자열을 사용하여 연락처를 검색합니다.

매개변수:

query (string, 필수): 검색 쿼리 문자열
readMask (string, 필수): 읽을 필드 (예: ‘names,emailAddresses,phoneNumbers’)
pageSize (integer, 선택사항): 반환할 결과 수. 최소: 1, 최대: 30
pageToken (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
sources (array, 선택사항): 검색할 소스. 옵션: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. 기본값: READ_SOURCE_TYPE_CONTACT

google_contacts/list_directory_people

설명: 인증된 사용자의 디렉토리에 있는 사람들을 나열합니다.

매개변수:

sources (array, 필수): 검색할 디렉토리 소스. 옵션: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. 기본값: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
pageSize (integer, 선택사항): 반환할 사람 수. 최소: 1, 최대: 1000
pageToken (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
readMask (string, 선택사항): 읽을 필드 (예: ‘names,emailAddresses’)
requestSyncToken (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false
mergeSources (array, 선택사항): 디렉토리 사람 응답에 병합할 추가 데이터. 옵션: CONTACT

google_contacts/search_directory_people

설명: 디렉토리에서 사람을 검색합니다.

매개변수:

query (string, 필수): 검색 쿼리
sources (string, 필수): 디렉토리 소스 (‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’ 사용)
pageSize (integer, 선택사항): 반환할 결과 수
readMask (string, 선택사항): 읽을 필드

google_contacts/list_other_contacts

설명: 기타 연락처를 나열합니다 (사용자의 개인 연락처에 없는).

매개변수:

pageSize (integer, 선택사항): 반환할 연락처 수. 최소: 1, 최대: 1000
pageToken (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
readMask (string, 선택사항): 읽을 필드
requestSyncToken (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false

google_contacts/search_other_contacts

설명: 기타 연락처를 검색합니다.

매개변수:

query (string, 필수): 검색 쿼리
readMask (string, 필수): 읽을 필드 (예: ‘names,emailAddresses’)
pageSize (integer, 선택사항): 결과 수

google_contacts/get_person

설명: 리소스 이름으로 한 사람의 연락처 정보를 가져옵니다.

매개변수:

resourceName (string, 필수): 가져올 사람의 리소스 이름 (예: ‘people/c123456789’)
personFields (string, 선택사항): 포함할 필드 (예: ‘names,emailAddresses,phoneNumbers’). 기본값: names,emailAddresses,phoneNumbers

google_contacts/create_contact

설명: 사용자의 주소록에 새 연락처를 만듭니다.

매개변수:

names (array, 선택사항): 사람의 이름들. 각 항목은 givenName (string), familyName (string), displayName (string)이 있는 객체.
emailAddresses (array, 선택사항): 이메일 주소들. 각 항목은 value (string, 이메일 주소)와 type (string, ‘home’, ‘work’, ‘other’, 기본값 ‘other’)이 있는 객체.
phoneNumbers (array, 선택사항): 전화번호들. 각 항목은 value (string, 전화번호)와 type (string, ‘home’, ‘work’, ‘mobile’, ‘other’, 기본값 ‘other’)이 있는 객체.
addresses (array, 선택사항): 우편 주소들. 각 항목은 formattedValue (string, 형식화된 주소)와 type (string, ‘home’, ‘work’, ‘other’, 기본값 ‘other’)이 있는 객체.
organizations (array, 선택사항): 조직/회사들. 각 항목은 name (string, 조직 이름), title (string, 직책), type (string, ‘work’, ‘other’, 기본값 ‘work’)이 있는 객체.

google_contacts/update_contact

설명: 기존 연락처의 정보를 업데이트합니다.

매개변수:

resourceName (string, 필수): 업데이트할 사람의 리소스 이름 (예: ‘people/c123456789’).
updatePersonFields (string, 필수): 업데이트할 필드 (예: ‘names,emailAddresses,phoneNumbers’).
names (array, 선택사항): 사람의 이름들. 각 항목은 givenName (string), familyName (string), displayName (string)이 있는 객체.
emailAddresses (array, 선택사항): 이메일 주소들. 각 항목은 value (string, 이메일 주소)와 type (string, ‘home’, ‘work’, ‘other’)이 있는 객체.
phoneNumbers (array, 선택사항): 전화번호들. 각 항목은 value (string, 전화번호)와 type (string, ‘home’, ‘work’, ‘mobile’, ‘other’)이 있는 객체.

google_contacts/delete_contact

설명: 사용자의 주소록에서 연락처를 삭제합니다.

매개변수:

resourceName (string, 필수): 삭제할 사람의 리소스 이름 (예: ‘people/c123456789’).

google_contacts/batch_get_people

설명: 한 번의 요청으로 여러 사람에 대한 정보를 가져옵니다.

매개변수:

resourceNames (array, 필수): 가져올 사람들의 리소스 이름 (최대 200개 항목).
personFields (string, 선택사항): 포함할 필드 (예: ‘names,emailAddresses,phoneNumbers’). 기본값: names,emailAddresses,phoneNumbers

google_contacts/list_contact_groups

설명: 사용자의 연락처 그룹(라벨)을 나열합니다.

매개변수:

pageSize (integer, 선택사항): 반환할 연락처 그룹 수. 최소: 1, 최대: 1000
pageToken (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
groupFields (string, 선택사항): 포함할 필드 (예: ‘name,memberCount,clientData’). 기본값: name,memberCount

google_contacts/get_contact_group

설명: 리소스 이름으로 특정 연락처 그룹을 가져옵니다.

매개변수:

resourceName (string, 필수): 연락처 그룹의 리소스 이름 (예: ‘contactGroups/myContactGroup’).
maxMembers (integer, 선택사항): 포함할 최대 멤버 수. 최소: 0, 최대: 20000
groupFields (string, 선택사항): 포함할 필드 (예: ‘name,memberCount,clientData’). 기본값: name,memberCount

google_contacts/create_contact_group

설명: 새 연락처 그룹(라벨)을 만듭니다.

매개변수:

name (string, 필수): 연락처 그룹의 이름.
clientData (array, 선택사항): 클라이언트별 데이터. 각 항목은 key (string)와 value (string)가 있는 객체.

google_contacts/update_contact_group

설명: 연락처 그룹의 정보를 업데이트합니다.

매개변수:

resourceName (string, 필수): 연락처 그룹의 리소스 이름 (예: ‘contactGroups/myContactGroup’).
name (string, 필수): 연락처 그룹의 이름.
clientData (array, 선택사항): 클라이언트별 데이터. 각 항목은 key (string)와 value (string)가 있는 객체.

google_contacts/delete_contact_group

설명: 연락처 그룹을 삭제합니다.

매개변수:

resourceName (string, 필수): 삭제할 연락처 그룹의 리소스 이름 (예: ‘contactGroups/myContactGroup’).
deleteContacts (boolean, 선택사항): 그룹 내 연락처도 삭제할지 여부. 기본값: false

사용 예제

기본 Google Contacts 에이전트 설정

from crewai import Agent, Task, Crew

# Google Contacts 기능을 가진 에이전트 생성
contacts_agent = Agent(
    role="연락처 관리자",
    goal="Google Contacts를 효율적으로 관리",
    backstory="연락처 관리 및 조직 전문 AI 어시스턴트.",
    apps=['google_contacts']  # 모든 Google Contacts 작업을 사용할 수 있습니다
)

# 새 연락처 생성 작업
create_contact_task = Task(
    description="'김철수'라는 이름으로 이메일 '[email protected]'과 전화번호 '010-1234-5678'로 새 연락처를 만드세요",
    agent=contacts_agent,
    expected_output="새 연락처가 성공적으로 생성됨"
)

# 작업 실행
crew = Crew(
    agents=[contacts_agent],
    tasks=[create_contact_task]
)

crew.kickoff()

문제 해결

일반적인 문제

인증 오류

Google 계정이 연락처 및 디렉토리 액세스에 필요한 권한을 가지고 있는지 확인하세요.
OAuth 연결이 Google People API에 필요한 모든 범위를 포함하는지 확인하세요.

연락처 생성/업데이트 문제

연락처 생성 시 email과 같은 필수 필드가 제공되는지 확인하세요.
연락처를 업데이트하거나 삭제할 때 resourceName이 올바른지 확인하세요.

도움 받기

도움이 필요하신가요?

Google Contacts 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 문의하세요.