Agent Engine 에이전트 등록
Gemini Enterprise 콘솔에서 Custom agent via Agent Engine을 등록하는 단계별 가이드
이미 Agent Engine에 배포된 에이전트를 Gemini Enterprise 카탈로그에 등록하는 절차입니다.
목차
1. 사전 준비
| 항목 | 비고 |
|---|---|
| ADK 기반 에이전트가 Agent Engine에 배포 완료 | gcloud ai reasoning-engines list로 확인 |
| Gemini Enterprise App이 이미 생성되어 있음 | Search/Assistant 등 어떤 유형이든 가능 |
| 본인이 해당 App의 Editor 이상 권한 보유 | |
| OAuth Client ID/Secret 준비 | OAuth 클라이언트 ID 생성 참고 |
2. Reasoning Engine 리소스 경로 확인
gcloud ai reasoning-engines list \
--region=us-central1 \
--format="table(name, displayName, updateTime)"
출력에서 다음 형식의 경로를 메모합니다.
projects/{PROJECT_NUMBER}/locations/us-central1/reasoningEngines/{REASONING_ENGINE_ID}
PROJECT_ID가 아닌 PROJECT_NUMBER 형태일 수 있습니다. 콘솔이 자동으로 변환해 줍니다.
3. Add agent 진입
- Gemini Enterprise 콘솔 → [Apps] → 대상 App 선택
- 상단 탭 중 [Agents] 클릭
- 우측 상단 [+ Add agent] 클릭
- Custom agent via Agent Engine 카드의 [Add] 선택
| 카드 | 선택 시점 |
|---|---|
| Custom agent via Agent Engine | ADK + Agent Engine 사용 |
| Custom agent via Dialogflow | Dialogflow CX 사용 |
| Custom agent via A2A | 외부 A2A 호환 서버 |
| Agents via Marketplace | 사전 검증된 서드파티 |
4. Authorizations 단계
4.1 Authorization 추가
- [Add authorization] 클릭
- 입력 항목
| 필드 | 값 |
|---|---|
| Authorization name | Google OAuth (식별용) |
| Client ID | OAuth 클라이언트 생성 시 받은 값 |
| Client secret | OAuth 클라이언트 생성 시 받은 값 |
| Token URI | https://oauth2.googleapis.com/token |
| Authorization URI | https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID |
| Scopes | openid email profile (도구가 추가 스코프를 요구하면 함께 입력) |
- [Done] → [Next]
4.2 추가 Authorization이 필요한 경우
- Tool이 Google API(Gmail, Drive 등)를 호출할 때 → 해당 스코프를 별도 Authorization으로 추가
- 사내 SaaS API 호출 → 해당 OAuth 서버 정보로 Authorization 추가
Authorization은 사용자별 Token을 안전하게 저장합니다. 평문 자격증명을 코드에 두지 마세요.
5. Configuration 단계
5.1 기본 정보
| 필드 | 설명 | 예시 |
|---|---|---|
| Agent name | 사용자에게 보일 이름 | Data Engineer Agent |
| Agent description | 한 줄 설명 | 자연어를 SQL로 변환하고 BigQuery에서 실행 |
| Agent icon | 아이콘(선택) | 부서 색상 활용 |
5.2 Agent Engine 연결
| 필드 | 값 |
|---|---|
| Agent Engine reasoning engine | 위에서 메모한 리소스 경로 전체 |
projects/123456789/locations/us-central1/reasoningEngines/3456789012345678
5.3 노출 범위
| 옵션 | 의미 |
|---|---|
| Available to all users | App에 접근 가능한 모든 End User에게 노출 |
| Restrict by group | 특정 그룹에만 노출 |
5.4 사용 예시(샘플 프롬프트)
End User가 처음 에이전트를 만났을 때 무엇을 시켜야 할지 제시하는 예시 문장입니다.
- 전월 대비 택시 이용 건수 증감률 분석
- 지난 7일간 결제 실패율이 가장 높은 매장 Top 10
- 내가 담당한 미해결 Jira 이슈 요약
- [Create] 클릭
6. 생성 확인
- Agents 목록으로 자동 이동
- 방금 등록한 항목이 Enabled 상태인지 확인
| 컬럼 | 확인 |
|---|---|
| Display name | 입력한 Agent name |
| Agent type | Agent Engine |
| Agent state | ✅ Enabled |
| Authorization | 등록한 Authorization 이름 |
- 우측의 [Open] 또는 [Test]로 챗 인터페이스 진입 → 다음 챕터의 테스트 및 모니터링 참고
7. CLI / API로 등록 (선택)
콘솔 외에도 Discovery Engine API로 자동화할 수 있습니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}/locations/global/collections/default_collection/engines/${APP_ID}/agents" \
-d '{
"displayName": "Data Engineer Agent",
"description": "Natural language to SQL on BigQuery",
"agentEngine": {
"reasoningEngine": "projects/123456789/locations/us-central1/reasoningEngines/3456789012345678"
},
"authorizations": ["projects/${PROJECT_ID}/locations/global/authorizations/google-oauth"]
}'
API 경로와 필드명은 v1alpha → v1 승격 과정에서 변경될 수 있습니다. 사용 시점의 공식 레퍼런스를 확인하세요.