ax 딥다이브
— 에이전트에게 작업실을 빌려주는 실행 플랫폼

1프로젝트 한줄 요약

ax는 에이전트 작업을 YAML로 선언하면, 필요한 작업 공간을 준비하고 격리된 환경에서 실행·중단·재개하도록 조정하는 플랫폼입니다. AX의 핵심은 모델에게 무엇을 말할지가 아니라, 에이전트가 어디서 어떤 자원으로 일하게 할지를 관리하는 데 있습니다.

예를 들어 코드 검사 에이전트 100개를 실행한다고 해 봅시다. 각 에이전트에는 저장소, 실행 명령, 메모리 한도, API 인증 정보가 필요합니다. 문제가 생기면 내부를 들여다봐야 하고, 오래 쉬는 작업은 멈췄다가 다시 이어가고 싶습니다. AX는 이 운영 문제를 세 가지 자원으로 나눕니다.

이 구조의 원본은 pkg/apis/v1alpha1/ax.proto입니다. 이름에 붙은 v1alpha1은 초기 단계 API임을 드러냅니다. 선언할 수 있는 필드와 실제 실행 경로에서 소비하는 필드는 구분해야 합니다. 특히 MCP·스킬의 구현 범위는 뒤에서 따로 확인합니다.

1-1. 사용자가 보는 흐름과 서버 안의 흐름

실행 파일은 세 개입니다. cmd/ax가 사용자의 CLI, cmd/ax-server가 제어 서버, cmd/ax-task-runner가 각 샌드박스 안의 시작점입니다. 서버와 실행기를 분리한 덕분에 사용자는 실행기 이미지를 바꿀 수 있습니다.

2왜 주목받는가

2026-10-23 GitHub Trending Go Monthly 1위, 스타 14,049개, 포크 732개입니다. 이 수치만으로 인기의 원인을 입증할 수는 없습니다. 다만 Google의 공개 에이전트 실행 기반이라는 위치와 아래 설계 선택들은 개발자가 이 저장소에 주목할 이유로 해석할 수 있습니다.

2-1. 에이전트의 운영을 별도 문제로 다룬다

README는 에이전트가 상태를 쌓고, 모델 API와 도구 서버에 접근하며, 반복 실행으로 비용을 소모할 수 있다고 설명합니다. AX는 이 문제에 격리, 자원 한도, 작업 공간 준비, 명시적인 중단·재개라는 관리 단위를 제공합니다. 에이전트 로직이 바뀌어도 실행 환경을 관리하는 규칙은 재사용할 수 있다는 점이 이 설계의 학습 가치입니다.

2-2. 익숙한 Kubernetes 문법, 다른 상태 저장소

apiVersion·kind·metadata·spec 형태와 apply·get·watch 명령은 Kubernetes와 닮았습니다. 하지만 Task를 Kubernetes CRD로 등록하는 구조는 아닙니다. DESIGN.md는 수많은 짧은 작업이 Kubernetes의 etcd에 주는 부담을 피하려고 Redis를 선택했다고 설명합니다.

여기서 배울 것은 특정 DB가 언제나 더 빠르다는 결론이 아닙니다. 인프라 배포를 관리하는 데이터와 대량의 작업 상태 데이터를 같은 저장 경로로 보내야 하는지 묻는 제어 경계의 설계입니다.

2-3. 기존 선택지와 비교하면 어디에 놓이는가

비교의 기준은 역할과 구조입니다. AX가 다른 도구보다 빠르거나 저렴하다는 실측 비교는 아닙니다. 특히 에이전트의 사고 흐름과 실행 인프라는 함께 조합할 수 있는 서로 다른 층입니다.

2-4. 작은 코드에서 분산 시스템의 현실을 만난다

자동 생성 코드를 제외한 Go 구현은 7,237줄이고, Go 테스트는 6,751줄입니다. internal/lock/lock.go에는 잠금 갱신 실패의 한계까지 주석으로 적혀 있습니다. runner/runner.go에는 자식 프로세스 종료, 종료 신호 전파, 정리 시간 제한이 한 파일에 모여 있습니다.

3기술 스택 전체 지도

3-1. 백엔드: Go 표준 라이브러리 위에 얇은 의존성

go.mod의 Go 지시문은 go 1.27.1입니다. docs/development.md는 Go 1.27 이상이라고 안내하지만, 실제 빌드 기준을 볼 때는 더 구체적인 모듈 선언을 먼저 읽습니다.

날짜와 커밋 식별자가 붙은 긴 Agent env 버전은 의사 버전입니다. 날짜·시간과 커밋 식별자를 포함해 특정 소스를 가리킵니다. 보기 편한 릴리스 이름이 없어도 의존성을 재현 가능한 위치에 고정하는 Go 모듈의 방법입니다.

// go.mod의 직접 의존성 중 일부
go 1.27.1
require (
    github.com/agent-substrate/substrate v0.5.0
    github.com/redis/go-redis/v9 v9.22.0
    google.golang.org/grpc v1.83.2
    google.golang.org/protobuf v1.36.12
    gopkg.in/yaml.v3 v3.0.1
)

net/http, flag, log/slog, os/exec 같은 Go 표준 패키지도 중요합니다. 별도의 웹 프레임워크나 Cobra 없이 서버와 CLI를 구성합니다. cmd/ax/main.go의 parseGlobalArgs()·runApply()를 읽으면 명령 처리의 기본을 직접 볼 수 있습니다.

3-2. 프론트엔드: 웹 화면 대신 CLI와 YAML

이 커밋에는 package.json과 React·Vue 같은 웹 앱이 없습니다. 사용자 접점은 ax CLI이며, cmd/ax/main.go 한 파일이 1,219줄입니다. 입력은 YAML, 요청은 gRPC, 출력은 표·상세 텍스트·YAML·상태 스트림입니다.

3-3. 실행 이미지와 모델 초기화

Dockerfile.task-runner는 python:3.12-slim을 기반으로 Git·curl·bash 등을 설치하고, Go 실행기와 cmd/ax-task-runner/antigravity_bootstrap.py를 넣습니다. Python은 129줄의 초기화 연결 코드에 사용됩니다.

google-antigravity는 pip install에 버전 고정 없이 선언되어 있습니다. Python 패키지용 pyproject.toml이나 잠금 파일은 없습니다. 따라서 Go 모듈 버전이 고정되었다고 해서 실행 이미지 전체의 의존성이 같은 수준으로 고정된 것은 아닙니다.

3-4. 인프라·빌드·CI

기술 스택을 읽을 때는 라이브러리 이름뿐 아니라 버전이 고정되는 경계와 실제 배포 경로까지 함께 확인해야 합니다. .ko.yaml의 실행기 기반은 alpine/git:latest로, Python을 포함하는 Dockerfile 경로와 다릅니다. 목표 기반 초기화에 필요한 도구가 어느 이미지에 들어가는지 구분해서 읽으세요.

4아키텍처 심화 분석

4-1. 시스템 구조도: 제어 서버 밖에서 실행되는 작업

AX가 직접 가상화 엔진을 구현하는 것은 아닙니다. internal/substrate/client.go의 BuildActorTemplate()는 샌드박스 클래스를 GVisor, 설정 이름을 gvisor-default로 지정합니다. 격리의 실제 동작과 지원 환경은 Substrate 쪽 구현·설정에도 달려 있습니다.

4-2. 패턴 ① 하나의 데이터 계약, 경계마다 다른 검증

pkg/apis/v1alpha1/ax.proto에 자원과 RPC를 함께 정의합니다. YAML은 pkg/apis/v1alpha1/types.go의 unmarshalYAMLWith()에서 일반 데이터로 읽은 뒤 JSON으로 변환하고, 마지막에 protojson으로 해석합니다. YAML과 RPC의 필드 이름·타입이 같은 계약을 따르게 하는 설계입니다.

// pkg/apis/v1alpha1/types.go의 옵션
protoUnmarshal = protojson.UnmarshalOptions{}
protoUnmarshalLenient = protojson.UnmarshalOptions{
    DiscardUnknown: true,
}

// 사용자 YAML: unmarshalYAML() → 엄격하게 해석
// 실행기 입력: UnmarshalYAMLLenient() → 모르는 필드는 무시

사용자가 memory를 memroy로 쓰면 빠르게 오류를 알려야 합니다. 반대로 새 서버가 추가한 필드를 오래된 실행기가 모른다는 이유로 작업 전체가 멈추면 업데이트가 어려워집니다. cmd/ax-task-runner/main.go의 loadSpec()가 관대한 해석을 사용하는 이유입니다.

커밋 0f085aa는 바로 이 실행기 호환성을 보완합니다. cmd/ax-task-runner/main_test.go의 TestLoadSpec_IgnoresUnknownFields()와 TestLoadSpec_WorkspaceIgnoresUnknownFields()가 그 의도를 보여 줍니다. 다만 모르는 필드를 무시한다는 것은 그 필드의 기능까지 구현한다는 뜻은 아닙니다.

4-3. 패턴 ② 인터페이스로 분리한 저장소와 직접 조정

internal/store/store.go의 Store는 저장·조회·삭제·감시 계약입니다. 실제 Redis 구현은 internal/store/redis/store.go, 테스트에 쓰기 쉬운 메모리 구현은 internal/store/memory/store.go에 있습니다. API 서버는 구체적인 Redis 명령 대신 이 인터페이스를 호출합니다.

internal/server/server.go의 CreateTask()는 검증과 잠금 획득 후 Task를 저장하고, 같은 요청 안에서 Reconcile()를 호출합니다. 이름이 controller라고 해서 별도 백그라운드 작업 큐가 모든 상태를 계속 재조정한다고 가정하면 안 됩니다.

README와 다른 중요한 지점: 빠른 시작의 출력은 apply 뒤 Running을 보여 주지만, 이 커밋의 생성 경로는 Suspended입니다. applyDocument()에도 자동 재개 호출이 없습니다. TestE2E_TaskLifecycleAndSubstrateSync() 역시 생성 후 별도의 ax resume task를 호출합니다.

Task의 명세는 생성 후 불변입니다. 이미 존재하는 Task를 다시 적용하면 보통 거절하며, Pending 상태에서 동일 명세로 생성 요청을 다시 보내는 복구 경로는 허용합니다. Workspace·Model의 생성 또는 갱신과 Task의 생성을 같은 동작으로 이해하지 마세요.

taskTemplateName()는 이미지와 환경변수를 정렬된 순서로 해시해 템플릿 이름에 넣습니다. 실행용 Task 복사본에서 Status를 제거하므로, 단순한 상태 변화가 새로운 시작 템플릿을 만들지 않습니다. 설정과 관측 상태를 분리하는 구체적인 예입니다.

Redis는 문서 저장·목록 조회·알림을 나누어 맡는다

SaveTask()는 TxPipeline()으로 자원 JSON 저장, 두 개의 정렬 집합 갱신, Pub/Sub 발행을 묶습니다. 기본 키는 ax:task:default:hello처럼 만들어집니다. 서버 시작 시 저장소 옵션은 비어 있어 Task 레코드 TTL은 기본적으로 설정되지 않습니다.

// internal/store/redis/store.go, SaveTask()의 핵심
pipe := s.client.TxPipeline()
pipe.Set(ctx, s.taskKey(atespace, name), data, s.opts.TTL)
pipe.ZAdd(ctx, s.taskIndexKey(), redis.Z{Score: score, Member: member})
pipe.ZAdd(ctx, s.taskAtespaceIndexKey(atespace), redis.Z{Score: score, Member: name})
pipe.Publish(ctx, s.taskPubSubChannel(atespace, name), data)
_, err = pipe.Exec(ctx)

WatchTask()는 먼저 구독을 준비하고 현재 값을 INITIAL로 보낸 뒤, 이후 알림을 MODIFIED로 전달합니다. Redis Pub/Sub는 과거 알림을 재생하는 영속 로그가 아닙니다. 연결이 끊긴 동안의 모든 변화를 보장하는 이벤트 저장소로 해석하면 안 됩니다.

4-4. 패턴 ③ 자원별 잠금과 갱신 가능한 임대

두 서버가 같은 Task를 동시에 중단·재개하면 상태가 꼬일 수 있습니다. internal/lock/lock.go의 RedisLocker.Lock()는 자원의 종류·atespace·이름을 키로 만들어 같은 자원에 대한 변경을 직렬화합니다. 서로 다른 Task 전체를 하나의 전역 잠금으로 묶지는 않습니다.

4-5. 패턴 ④ 실행기 수명주기와 상태 신호의 분리

runner/runner.go의 Run()은 메타데이터 서버를 시작하고 작업 공간을 준비한 뒤, 사용자 명령을 별도 프로세스 그룹으로 실행합니다. 명령 종료를 감지해도 실행기는 취소 신호를 기다리며 살아 있습니다. 사용자 명령의 종료, 샌드박스의 생존, 작업 공간의 준비 상태는 서로 다른 사실로 관리됩니다.

// runner/runner.go, Run()에서 발췌
exited := make(chan error, 1)
go func() { exited <- cmd.Wait() }()

select {
case err := <-exited:
    reportExit(cfg, cmd, err)
    // 명령이 끝나도 점검할 수 있도록 실행기를 유지한다.
    <-ctx.Done()
case <-ctx.Done():
    reportExit(cfg, cmd, stopCommand(cmd, exited))
}

stopCommand()는 프로세스 그룹에 SIGTERM을 보내고 10초를 기다린 뒤, 끝나지 않으면 SIGKILL을 보냅니다. 자식이 만든 하위 프로세스까지 함께 정리하려고 Setpgid: true와 음수 PID를 사용합니다.

OnCommandExit 훅은 있지만 기본 실행기의 main()은 이를 서버 상태 갱신에 연결하지 않습니다. 그러므로 명령이 정상 종료했다고 Task가 자동으로 Completed가 된다고 가정하면 안 됩니다. TestRun_KeepsServingAfterCommandExits()는 실행기를 계속 유지하려는 의도를 보여 줍니다.

특히 SetupWorkspace()는 Git 실패를 기록하고 초기화 마커 생성을 생략해도 nil 오류를 반환합니다. Run()은 오류가 없으면 준비 상태를 참으로 만들고 SetupResult의 세부 결과를 확인하지 않습니다. 초기화 에이전트의 실패·건너뛰기도 치명적 오류가 아닙니다. 조정기는 한 번 참이 된 WorkspaceReady 조건을 중단·재개 후에도 재사용합니다. 준비 상태와 실제 준비 품질 사이의 차이를 읽는 연습이 됩니다.

메타데이터는 127.0.0.1:8099, 외부 준비 확인과 게스트 서비스는 기본 :80으로 분리합니다. internal/metadata/server.go의 NewServer()는 spec.debug가 참일 때만 프로세스 실행·파일 접근 게스트 서비스를 등록합니다. 사용 가능한 기능에 따라 노출 면적을 줄이는 설계입니다.

5디렉토리 구조 해부

cmd/는 각 실행 파일의 입구입니다. 실제 동작 대부분은 internal/과 runner/에 있습니다. Go의 internal 경로는 바깥 프로젝트의 임의 가져오기를 제한합니다. 반면 공개 runner 패키지는 사용자 이미지가 runner.Run()을 호출하도록 제공하는 확장 지점입니다.

5-1. 코드 규모를 분리해서 보기

커밋 0f085aa의 확장자별 물리적 줄 수입니다. 빈 줄·주석을 포함하며 Git 내부 파일은 제외합니다. 자동 생성 코드를 분리해야 실제로 읽어야 할 구현 규모가 보입니다.

생성 코드를 뺀 Go 13,988줄 중 테스트는 약 48.3%입니다. 이는 줄 수의 비중이며 코드 커버리지 수치가 아닙니다. 초보자는 생성 코드 3,458줄부터 읽기보다, 계약을 정의한 proto와 테스트가 설명하는 동작부터 읽는 편이 좋습니다.

6학습 포인트 (기술별)

6-1. Go 인터페이스: 저장소를 바꿀 수 있게 만들기

store.Store, lock.Locker, server.Reconciler는 구현 교체 경계입니다. 서버가 Redis 클라이언트를 직접 받는 대신 저장소 계약을 받으면, 빠른 테스트에는 메모리 구현을 넣을 수 있습니다. server.NewServer()가 Options로 잠금과 조정기를 주입받는 부분을 함께 읽으세요.

실습 아이디어: CreateTask()가 실제로 사용하는 인터페이스 메서드만 표시한 의존성 표를 그려 보세요. “인터페이스가 있으면 좋다”를 넘어, 외부 서비스를 어느 지점에서 대체할 수 있는지 설명하는 것이 목표입니다.

6-2. YAML과 Protobuf: 직렬화도 제품의 계약이다

pkg/apis/v1alpha1/types.go의 YAML→JSON→Protobuf 변환은 필드 명명 규칙을 한곳에 모읍니다. pkg/apis/v1alpha1/ax.proto의 worker_ip에는 json_name = "workerIP"를 명시해 기존 표기를 유지합니다. 내부 언어의 관례와 외부 사용자에게 약속한 이름을 구분하는 예입니다.

실습 아이디어: 정상 YAML, 오타 필드가 있는 YAML, 새 필드가 추가된 YAML을 종이에 작성하고, CLI와 실행기가 각각 수락할지 예상해 보세요. pkg/apis/v1alpha1/types_test.go와 실행기 테스트에서 근거를 찾습니다.

6-3. Redis: 데이터와 알림은 역할이 다르다

Task의 현재 값은 문자열 키, 목록은 정렬 집합, 변화 알림은 Pub/Sub입니다. 같은 Redis를 사용하지만 자료구조마다 보장하는 동작은 다릅니다. GetTask()가 읽는 경로와 WatchTask()가 듣는 경로를 별도로 추적해 보세요.

실습 아이디어: watcher가 연결되지 않은 동안 상태가 두 번 변했다고 가정하세요. 다시 연결했을 때 현재 값으로 알 수 있는 사실과, 알림 기록 없이는 알 수 없는 사실을 두 열로 적어 봅니다.

6-4. 동시성과 취소: 일을 시작한 사람이 정리도 책임진다

context.Context는 시간 제한과 취소를 하위 동작에 전달합니다. Run()의 버퍼가 1인 종료 채널은 프로세스 종료 결과 하나를 전달하고, 잠금의 sync.Once는 해제 동작이 중복 호출돼도 한 번만 수행되게 합니다.

실습 아이디어: 명령이 먼저 끝나는 경우, 취소가 먼저 오는 경우, SIGTERM을 무시하는 경우를 각각 시간축으로 그리세요. 어느 goroutine이 무엇을 기다리고 누가 채널에 쓰는지 표시하면 됩니다.

6-5. 재시도: 일시적 실패와 잘못된 입력 구분하기

internal/substrate/client.go의 retryOnCodes()는 최대 10회, 초기 간격 200ms, 최대 간격 2초의 지수 백오프를 사용합니다. Git 준비는 최대 5회, 실패 사이 2초 간격으로 별도 구현합니다. 실패가 같아 보여도 상대 서비스와 작업 성격에 따라 재시도 정책이 다릅니다.

실습 아이디어: 네트워크 일시 단절, 잘못된 메모리 단위, 없는 이미지 이름을 분류해 보세요. IsTransientError()와 ValidateResources() 중 어느 경계가 먼저 책임져야 할지 설명합니다.

6-6. 준비 상태와 보안: 이름보다 실제 조건 읽기

internal/metadata/server.go는 메타데이터와 원격 실행 서비스를 다른 리스너로 나누고, 디버그 설정에 따라 게스트 서비스를 켭니다. cmd/ax-task-runner/antigravity_bootstrap.py는 파일 도구에 작업 디렉터리 정책을 적용하면서 명령 실행도 허용합니다. 이 정책과 OS 수준의 격리는 서로 다른 층입니다.

실습 아이디어: “Task가 Running이다”, “/readyz가 200이다”, “Git 준비가 성공했다”, “사용자 명령이 성공했다” 사이에 성립하는 관계만 화살표로 연결하세요. 소스에 없는 보장을 추가하지 않는 것이 핵심입니다.

7하드웨어 / 시스템 요구사항

저장소에는 개발용 PC의 공식 최소 RAM·디스크 용량이나, 작업 수에 따른 용량 산정표가 없습니다. 필요 자원은 AX 제어 서버, Redis, Substrate 작업자, 실제 에이전트 작업의 몫을 나누어 계산해야 합니다. 아래 수치는 성능 측정값이 아니라 배포 예시의 설정값입니다.

100m은 CPU 0.1코어, 1000m은 1코어입니다. 두 제어 구성요소의 요청 합계는 CPU 0.2코어·메모리 256Mi이지만, Kubernetes 자체와 Substrate·실제 작업은 빠져 있으므로 노트북 전체의 최소 사양으로 사용할 수 없습니다.

7-1. Task의 자원 제한은 Kubernetes Pod와 다르다

pkg/apis/v1alpha1/resources.go의 ValidateResources()는 spec.resources.requests의 CPU나 메모리 값이 비어 있지 않으면 거절합니다. 스키마에 필드가 있어도 자원 크기 지정에 지원하는 설정은 limits뿐입니다. CPU·메모리는 양수여야 하고, CPU는 1,000코어 미만이어야 합니다. 생략하면 작업자 기본 설정을 따릅니다.

# Task.spec 안의 예시: Pod의 requests와 혼동하지 않는다.
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"

이 값은 internal/substrate/client.go의 ResourceLimits()를 통해 ActorTemplate로 전달됩니다. 제한을 요청한 작업에 템플릿 생성이 실패했을 때, 다른 기본 템플릿으로 조용히 대체하지 않도록 제어 코드가 오류를 반환합니다.

7-2. GPU·모델·외부 연결

기본 배포에는 GPU 자원 요청이 없고, 모델 클라이언트는 외부 생성 API를 호출하는 구조입니다. 따라서 AX 제어 기능 자체를 배우기 위해 GPU가 필요하다는 근거는 없습니다. 다만 사용자가 실행할 이미지가 로컬 추론이나 무거운 빌드를 포함한다면 그 작업의 요구사항을 별도로 계산해야 합니다.

모델 기반 초기화에는 이미지 안의 초기화 스크립트와 GEMINI_API_KEY가 필요합니다. 기본 제한 시간은 10분이며 AX_BOOTSTRAP_TIMEOUT으로 조정합니다. Git 다운로드, 이미지 다운로드, 모델 API 호출, 스냅샷 저장소는 각각 네트워크 접근과 인증 구성이 필요할 수 있습니다.

8직접 해볼 수 있는 실습 과제

앞의 두 과제는 파일 열람만으로 끝낼 수 있습니다. 실행 실험은 Substrate가 준비된 별도의 학습용 클러스터를 전제로 합니다. 각 과제는 명령 실행 자체보다 예상한 상태와 실제 구현이 일치하는지 설명하는 것을 완료 기준으로 삼습니다.

apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: study-ws
spec:
  files:
    - path: message.txt
      content: "AX 학습용 파일"
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: study-task
spec:
  workspace:
    name: study-ws
  debug: true
  resources:
    limits:
      cpu: "500m"
      memory: "512Mi"
  command: ["sh", "-c", "pwd; cat message.txt"]

# study.yaml로 저장한 뒤, 준비된 학습용 클러스터에서 관찰
ax apply -f study.yaml
ax get task study-task
# 생성 직후 예상 단계: Suspended

ax resume task study-task
ax describe task study-task
ax ssh study-task -- cat /workspace/message.txt

ax suspend task study-task
ax resume task study-task
ax delete task study-task
ax delete workspace study-ws

9관련 기술 심화 학습 로드맵

Go 문법을 막 배웠다면 하루 30~60분의 읽기·메모를 기준으로 다음 순서를 활용할 수 있습니다. 일정은 학습용 제안이며, 각 주의 결과물을 설명할 수 있을 때 다음 단계로 넘어가세요.

학습의 다음 단계는 비슷한 도구를 더 외우는 것이 아니라, 한 동작의 성공·실패·재시도 계약을 끝까지 설명하는 것입니다. 예를 들어 “재개가 실패했다”는 한 문장을 요청 취소, Substrate 오류, 준비 확인 시간 초과, 사용자 명령 실패로 분해할 수 있다면 시스템을 층별로 읽기 시작한 것입니다.

9-1. 관심사별 다음 갈림길

• 백엔드: RPC 오류 코드, 스트리밍 재연결, 취소 전파, 저장소의 동시성 계약을 더 공부합니다.
• 인프라: 샌드박스의 격리 경계, 볼륨 스냅샷, 작업자 용량, Redis 영속성과 고가용성을 공부합니다.
• 에이전트 플랫폼: 도구 권한, 초기화 정책, 모델 인증 정보 전달, 비용·시간 예산의 실제 집행을 공부합니다.
• 테스트: 메모리 대체 구현, 가짜 gRPC 서버, 실제 Kind E2E가 각각 잡는 실패를 비교합니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 읽기 순서

• google/ax 공식 저장소 — 소개, 릴리스, 이슈의 출발점.
• AX 설계 문서 — Redis를 선택한 이유와 RPC 구성.
• 핵심 개념 · 선언 명세 — 자원과 필드의 의미.
• 사용자 실행기 계약 · 샌드박스 안내 — 이미지·메타데이터·게스트 서비스.
• 네트워크 안내 · 개발 안내 — 연결과 빌드의 전제.
• 로드맵 — 구현 완료 기능과 향후 목표 구분.

11-2. 코드 근거 바로가기

• go.mod · ax.proto · YAML 변환과 검증.
• API 핸들러 · Task 조정기 — 생성·재개·중단의 실제 경로.
• 분산 잠금 · Redis 저장소 — 임대와 현재 상태·알림.
• 실행기 핵심 · 작업 공간 초기화 — 명령 종료와 준비 상태의 차이.
• 환경 계획 모듈 · 모델 클라이언트 — 기본 실행 경로와의 연결 여부 확인.
• E2E 테스트 · E2E CI 설정 — 수명주기 검증의 의도.

11-3. 관련 기술의 공식 학습 자료

• Agent Substrate — AX 아래의 실행 기반.
• Go 둘러보기 · Go의 context 설명 — 언어 기초와 취소 전파.
• Go용 gRPC 안내 · Protocol Buffers 언어 안내 — 서비스와 데이터 계약.
• Redis Pub/Sub · Redis 트랜잭션 — 알림과 데이터 변경의 차이.
• Kubernetes Job · gVisor 문서 — 배치 작업과 격리 실행의 배경.
• ko · Kind — Go 이미지 빌드와 학습용 클러스터.
• MCP 소개 — 도구 연결 프로토콜의 기본 개념.

현재 상태 (2026-10-23 확인)

최근 push 시각과 분석 기준 커밋의 날짜는 서로 다른 정보입니다. 최신 릴리스 v0.3.1의 코드와 이 글이 설명하는 0f085aa의 코드 역시 같다고 가정하지 마세요. 줄 수는 해당 커밋의 물리적 줄 수 집계입니다.