Go용 ADK가 포함된 에이전트 시작 패키지

1. 소개

Go를 사용한 ADK

Python은 모델 학습 및 연구에 여전히 많이 사용되지만, AI 에이전트의 제공 및 오케스트레이션 요구사항은 낮은 지연 시간, 높은 동시성, 유형 안전성과 같은 Go의 강점과 밀접하게 관련되어 있습니다.

프로토타입에서 프로덕션 에이전트로 전환하면 Go가 매우 잘 처리할 수 있는 엔지니어링 문제가 발생합니다. Go의 정적 타이핑은 구조화된 LLM 출력을 파싱할 때 런타임 오류를 방지합니다. OS 스레드의 경우 수 메가바이트인 반면 스택 메모리가 몇 킬로바이트에 불과한 경량 goroutine을 통해 에이전트는 과도한 스레드 관리 오버헤드 없이 수천 개의 동시 도구 실행을 처리할 수 있습니다.

Google의 에이전트 개발 키트 (ADK)는 이러한 아키텍처의 장점과 생성형 AI 간의 격차를 해소합니다. 이 가이드에서는 새 프로젝트를 스캐폴딩하고 Google Cloud에 보안 마이크로서비스로 배포합니다.

수행할 작업:

  • 에이전트 스타터 팩을 사용하여 프로덕션 준비가 완료된 에이전트 프로젝트 스캐폴드
  • 로컬 에이전트 개발 키트 웹 UI를 활용하여 에이전트 디버그 및 테스트
  • Go 기반 ADK 에이전트 로직 개발 및 이해
  • 단위 및 엔드 투 엔드 (E2E) 테스트 실행
  • Cloud Run에 에이전트를 안전하게 배포

필요한 항목:

  • 웹브라우저(예: Chrome)
  • 결제가 사용 설정된 Google Cloud 프로젝트

2. 시작하기 전에

Google Cloud 프로젝트 만들기

아직 토큰이 없다면 다음 단계를 따르세요.

  1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
  2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Shell 시작

Cloud Shell은 Google Cloud에서 실행되는 명령줄 환경으로, 필요한 도구가 미리 로드되어 제공됩니다. 이 실습의 기본 개발 환경으로 사용됩니다.

  1. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
  2. Cloud Shell에 연결되면 다음 명령어를 실행하여 Cloud Shell에서 인증을 확인합니다.
gcloud auth list
  1. 다음 명령어를 실행하여 프로젝트가 gcloud와 함께 사용하도록 구성되어 있는지 확인합니다.
gcloud config get project
  1. 프로젝트가 예상대로인지 확인한 후 아래 명령어를 실행하여 프로젝트 ID를 설정합니다.
export PROJECT_ID=$(gcloud config get project)

3. 에이전트 스타터 팩 시작하기

다행히 처음부터 시작할 필요는 없습니다. 에이전트 스타터 팩은 CI/CD 파이프라인, 인프라 구성, 상용구 코드를 비롯한 프로덕션에 즉시 사용 가능한 폴더 구조를 스캐폴딩하는 CLI 도구입니다.

시작하려면 uvx를 사용하여 빌드 생성 명령어를 실행하면 됩니다.

uvx agent-starter-pack create

CLI에서 대화형 설정을 안내합니다. 이 프로젝트에서는 다음 옵션을 선택합니다.

  • 프로젝트 이름: my-first-go-agent
  • 템플릿: 옵션 6 (Go ADK, A2A를 사용하는 Go 에이전트)
  • CI/CD: 옵션 3 (GitHub Actions)
  • 지역: us-central1

에이전트 스타터 팩 설정

녹색 성공! 메시지가 표시되면 계속 진행할 수 있습니다.

성공 메시지

4. 에이전트를 로컬에서 시각화

ADK의 가장 편리한 기능 중 하나는 에이전트를 배포하기 전에 시각적으로 디버그할 수 있다는 점입니다. 아래 명령어를 실행하면 내장 UI가 있는 로컬 개발 서버가 실행됩니다. 예, 채팅 창이 있지만 이벤트, 도구 호출 등을 추적하여 그 이상을 수행합니다.

프로젝트 디렉터리로 변경하고 playground를 시작합니다.

cd my-first-go-agent
make install
make playground

플레이그라운드가 실행되면 Cloud Shell에서 웹 미리보기를 열어 새로 만든 에이전트와 상호작용합니다.

에이전트는 에이전트 AI의 기본이 된 프레임워크인 ReAct (Reasoning and Acting) 패턴으로 구성됩니다. ReAct 패턴의 지속적인 '생각', '행동', '관찰' 루프는 문제 해결 및 해석 가능성을 향상시켜 에이전트의 의사 결정 과정을 투명하게 만듭니다.

예를 들어 날씨를 물으면 에이전트가 의도를 인식하고 get_weather 도구를 호출하여 구조화된 데이터를 반환합니다.

Playground UI

5. 코드 이해하기

이제 에이전트의 작동을 확인했으므로 이를 가능하게 하는 Go 코드를 살펴보겠습니다. 로직은 agent/agent.go에 있습니다. 이 파일은 도구 정의, 모델 구성, 초기화를 처리합니다.

ADK는 표준 Go 구조체를 사용하여 대규모 언어 모델 (LLM)이 코드와 상호작용하는 방식을 정의합니다. 날씨 도구의 입력 매개변수를 정의하려면 json 및 jsonschema 태그가 있는 구조체를 정의합니다.

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

GetWeatherResult는 도구가 실행된 후 에이전트에게 반환되는 데이터의 구조를 정의합니다.

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

GetWeather는 tool.Context와 인수 구조체를 허용하고 비즈니스 로직을 실행하며 결과 구조체를 반환하는 표준 Go 함수입니다.

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

NewRootAgent 함수는 애플리케이션 런처에 필요한 agent.Agent 인스턴스를 어셈블하고 반환합니다. 모델 구성을 초기화하고 genai.BackendVertexAI로 지원되는 gemini-2.5-flash 모델 인스턴스를 만들어 시작합니다.

그런 다음 로컬 GetWeather 함수를 functiontool로 래핑하여 Go 코드와 LLM 간의 격차를 해소합니다. 이 단계에서는 get_weather이라는 이름으로 도구를 등록하고 모델 컨텍스트에 필요한 설명을 제공합니다. 마지막으로 초기화된 Gemini 모델, 에이전트의 동작을 정의하는 시스템 명령어, 사용 가능한 도구 슬라이스를 단일 단위로 결합하는 llmagent.New를 사용하여 에이전트를 구성합니다.

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

6. 테스트

이 프로젝트에는 내부 로직의 단위 테스트와 서버 통합의 엔드 투 엔드 테스트가 모두 포함되어 있습니다.

agent/agent_test.go에서 GetWeather 함수는 출력 문자열이 예상과 일치하는지 확인하기 위해 테스트 사례 모음과 함께 호출됩니다.

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

엔드 투 엔드 테스트는 에이전트가 서버로 실행될 때 올바르게 작동하는지 확인하며, 특히 A2A 또는 에이전트 간 프로토콜 지원이 올바르게 작동하는지 확인합니다. E2E 테스트는 서버의 실제 인스턴스를 시작하고, 서버에 HTTP 요청을 전송하고, 응답을 확인합니다.

e2e/integration/server_e2e_test.go의 스니펫은 다음과 같습니다.

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

makefile을 사용하여 모든 테스트를 로컬에서 실행할 수 있습니다.

make test

7. 배포

전 세계와 에이전트를 공유하거나 프로덕션 생태계에 연결할 준비가 되면 포함된 배포 명령어를 실행합니다.

make deploy

이 명령어는 --source . 플래그에 의해 트리거되어 Google Cloud 빌드팩을 사용하여 소스에서 애플리케이션을 자동으로 빌드합니다. 이 이미지는 LLM 작업을 위한 충분한 RAM을 제공하는 --memory "4Gi"와 CPU가 24시간 할당된 상태를 유지하여 콜드 스타트를 방지하고 에이전트 상호작용에서 빠른 응답을 보장하는 --no-cpu-throttling 등 여러 프로덕션 최적화 플래그와 함께 Cloud Run에 배포됩니다.

에이전트가 안전하게 실행되도록 시스템은 기본적으로 모든 공개 액세스를 차단하는 --no-allow-unauthenticated를 사용하여 엄격한 구성으로 배포되므로 모든 요청에 Identity and Access Management (IAM) 인증이 필요합니다. 또한 GOOGLE_GENAI_USE_VERTEXAI=True를 비롯한 환경 변수를 삽입합니다.

배포 서비스 URL

IAP 사용 설정

IAP가 사용 설정되고 이메일이 주 구성원으로 추가되면 배포 후 제공된 서비스 URL로 이동할 수 있습니다. 기본 서비스 URL을 보면 배포된 에이전트 카드를 확인할 수 있습니다. 이 JSON 구조는 에이전트의 표준 인터페이스 역할을 하므로 다른 에이전트, 오케스트레이터 또는 사용자 대상 UI에서 동적으로 검색하고 사용할 수 있습니다.

상담사 카드

8. 삭제

Google Cloud 계정에 지속적으로 비용이 청구되지 않도록 하려면 이 Codelab 중에 생성된 리소스를 삭제하세요.

Cloud 프로젝트를 삭제하면 프로젝트 내에서 사용되는 모든 리소스에 대한 비용 청구가 중지됩니다.

gcloud projects delete $PROJECT_ID

Cloud Shell 디스크에서 Codelab 프로젝트 디렉터리를 삭제할 수도 있습니다.

rm -rf ~/my-first-go-agent

9. 축하합니다.

🎊 미션 완료! 에이전트 개발 키트를 사용하여 Go에서 AI 에이전트를 스캐폴딩하고 테스트하고 배포했습니다.

달성한 내용:

  • 에이전트 스타터 팩을 사용하여 초기 구조화된 기준을 스캐폴딩했습니다.
  • 에이전트 UI와 코드를 로컬에서 확인하고 테스트했습니다.
  • 타입이 지정된 스키마와 LLM 동작을 Go 객체에 매핑하는 함수를 살펴봤습니다.
  • Cloud Run에 Go 서비스를 배포했습니다.

다음 단계

  • ADK 문서: 고급 패턴, 멀티 에이전트 오케스트레이션, 메모리 시스템에 관한 전체 가이드
  • 에이전트 스타터 팩: 멀티 에이전트 시스템 및 복잡한 아키텍처를 포함한 템플릿 살펴보기
  • Cloud Run 문서: 성능 최적화, 확장 전략, 보안 권장사항에 관한 자세한 정보
  • Go 동시 실행 패턴: 고루틴과 채널을 이해하면 더 효율적인 에이전트 도구를 빌드하는 데 도움이 됩니다.
  • Vertex AI Agent Engine: 기본 제공 조정 및 도구로 관리되는 에이전트 인프라