Agent Executor (AX)

[!WARNING]
🚧 AX는 현재 활발한 초기 개발 단계에 있습니다.

저희는 코어, 재개 프로토콜 (resumption protocols), 그리고 런타임 사양 (runtime specifications)을 적극적으로 개선하고 있으며, 이 과정에서 안정적인 릴리스 이전에 주요한 중단적 변경 사항 (breaking changes)이 발생할 수 있습니다.

임시 정책: 코어 아키텍처를 안정화하는 동안 외부 Pull Request 수락을 일시적으로 중단합니다. 대신 피드백과 기능 요청을 위한 Issue를 생성해 주시는 것을 적극 권장합니다.

이 프로젝트를 곧 널리 알릴 예정입니다. 저희와 협업하는 데 관심이 있으시다면, ax-dev@google.com으로 연락해 주세요!

AX는 Agent eXecutor의 약자로, 분산 에이전트 런타임 (distributed agent runtime)입니다. AX는 에이전트 루프 (agentic loops)를 조정하고, 이벤트 로깅 (event logging)과 함께 실행을 관리하며, 로컬 및 원격 액터 (actors) 모두와 통신하는 런타임을 제공합니다. AX는 복잡한 분산 설정에서도 복구 (recovery) 및 실행 재개 (execution resumption)를 네이티브로 지원하도록 설계되어 신뢰성을 보장합니다.

특징 (Features)

• 분산 런타임 (Distributed Runtime): 컨트롤러 (Controller), 스킬 (skills), 도구 (tools), 에이전트 (agents)가 격리된 상태로 실행될 수 있음
• 재개 (Resumption): 실패 또는 중단으로부터의 자동 복구
• 스킬, 도구, 에이전트 (Skills, Tools, Agents): 스킬, 도구 및 에이전트 선택과 실행 지원
• 감사 및 정책 (Auditing & Policy): 모든 사용자 및 에이전트 호출은 공통 컨트롤러에 의해 조정되므로, 전체 실행과 스킬/도구/에이전트 호출을 쉽게 제어하고 감사할 수 있음
• 이식성 (Portability): 어디에서나 실행 가능하며, 소규모 및 대규모 배포로 확장 가능
• 커스터마이징 가능성 (Customizability): 하네스 (harness) 및 모델에 구애받지 않음

내장된 일관성 및 재개 가능 기능:

• 단일 작성자 아키텍처 (Single-Writer Architecture): 단일 컨트롤러가 일관된 상태 관리 (state management)를 보장
• 이벤트 로그 (Event Log): 자동 복구가 가능한 내구성이 있는 실행 상태 (durable execution state)
• 고급 재개 (Advanced Resumption): 호환 가능한 플랫폼에서 컴퓨팅 레이어 액터 재개 (compute-layer actor resumption) 지원

데모 (Demo)

Agent Substrate에 배포되었을 때 AX가 어떻게 작동하는지 데모를 통해 확인해 보세요.

개요 (Overview)

%%{init: {"flowchart": {"diagramPadding": 80}}}%%
graph LR
    Client
...

에이전트(Agents)가 단순한 보조 도구에서 자율적인 장기 실행 워커(Long running workers)로 진화함에 따라, 개발자들은 상태(State)를 관리하고, 신뢰성을 보장하며, 실행 과정을 감사(Audit)할 수 있는 강력한 런타임(Runtime)이 필요합니다. 도구(Tools), 기술(Skills), 에이전트가 격리된 액터(Actors)로 배포되는 분산 하네스(Distributed harnesses)로 이동함에 따라, 동적으로 생성된 격리된 워커(Isolated workers)를 갖춘 분산 런타임이 필수적이 되고 있습니다. AX는 이러한 격차를 메우기 위한 기초 계층(Foundational layer)을 제공합니다.

AX는 컴퓨팅 환경에 구애받지 않지만(Compute-agnostic), Kubernetes 상에서 최상의 경험을 제공하는 것을 목표로 합니다.

우리는 모든 정교한 에이전트 애플리케이션(Agentic application)이 AX가 제공하는 기능을 필요로 할 것이라고 예상합니다. 우리는 개발자들이 인프라보다는 애플리케이션 구축에 집중할 수 있도록, 이 계층을 널리 사용 가능한 기반으로 구축하고 있습니다. 우리는 안정적인 릴리스(Stable release)가 나오기 전에 모든 설계 결정(Design decision)을 검증하기 위해 이 프로젝트를 공개적으로 구축하기로 결정했습니다. 여러분의 피드백을 적극 권장합니다.

설치 (Installation)

저장소에서 ax CLI를 직접 설치하세요:

go install github.com/google/ax/cmd/ax@latest

설치 확인 (Verify Installation)

ax가 올바르게 설치되었는지 확인하세요:

ax --help

ax CLI의 사용법 정보가 표시되어야 합니다.

Kubernetes

AX는 Kubernetes 상의 Agent Substrate에서 네이티브로 지원되며, 이는 프로덕션(Production) 환경 사용을 위한 권장 배포 옵션입니다. 설정 및 구성에 대한 자세한 내용은 배포 가이드를 참조하세요.

Kubernetes에서 에이전트 워크로드(Agentic workloads)에 더 높은 밀도(Density)를 제공하는 이 새로운 계층에 대해 더 자세히 알아보세요.

빠른 시작 (Quick Start)

1. 실행 (Execute)

CLI는 AX 바이너리에 이미 연결된 에이전트와 내장 도구(Built-in tools)를 사용하여 쉽게 실행할 수 있는 방법을 제공합니다.

# 기본 ax.yaml 사용
ax exec --input "Can you list me this directory?"

...

대화는 언제든지 이어갈 수 있습니다:

ax exec \
  --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \
  --input "Show me the contents of README.md"

클라이언트의 연결이 끊어진 경우, 클라이언트가 놓친 이벤트들을 다시 재생(replay)할 수 있도록 마지막으로 확인한 시퀀스(sequence)를 전달하세요. 이는 클라이언트를 최신 상태로 따라잡게(catch up) 하는 것이지, 대화를 되감는(rewind) 것이 아닙니다. 체크포인트(checkpoint)로부터 분기(branch)하려면 대신 ax fork를 사용하세요.

이 예시에서는 시퀀스 번호 12번부터 클라이언트를 따라잡습니다:

ax exec \
  --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \
  --last-seq 12 \
...

기본적인 계획(planning) 단계를 실행하는 대신, 등록된 임의의 에이전트(agent)로부터 실행을 시작할 수 있습니다:

ax exec \
  --agent coding \
  --input "Can you write me a simple HTTP server in Python?"

에이전트 실행 중 문제가 발생하면, 대화 내에서 완료되지 않은 실행을 재개(resume)할 수 있습니다:

ax exec \
  --conversation edf98ef5-4bb1-4a9e-a091-3a77e03727e6 \
  --agent "coding" \
...

2. 커스텀 에이전트(Custom Agents)로 실행하기

대부분의 개발자는 자신만의 에이전트를 구축하기를 원합니다. AX는 커스텀 에이전트를 원격(remote) 또는 샌드박스(sandbox) 에이전트로 실행할 수 있게 해줍니다. 지원되는 에이전트의 전체 목록은 Custom Agents를 참조하세요.

이 예시는 AX 서버가 AgentService.Connect RPC를 통해 원격 에이전트를 어떻게 실행하는지 보여줍니다.

터미널 1 - 원격 에이전트 서버 시작:

go run examples/remote_agent/main.go

원격 에이전트는 :50051 포트에서 AgentService를 구현하는 gRPC 서버로 실행됩니다.

터미널 2 - AX 컨트롤러(controller) 서버 시작:

# 에이전트가 ax.yaml에 원격 에이전트로 등록되어 있는지 확인하세요.
cat ax.yaml
# ...
...

서버는 기본적으로 :8494 포트에서 서비스를 노출합니다.

터미널 3 - 원격 에이전트를 등록하고 실행:

ax exec \
    --server localhost:8494 \
    --input "HELLO, CAN YOU LOWERCASE WHAT I JUST SAID?"

사용법 (Usage)

ax 명령어는 여러 서브커맨드(subcommands)를 제공합니다:

Execute

ax exec \
    [--input <text>] \
    [--conversation <id>] \
...

새로운 에이전트 실행 (agentic execution)을 수행하거나 기존 실행을 자동으로 재개합니다. 만약 대화 ID (conversation ID)가 이미 존재한다면, 실행은 마지막 상태로부터 재개됩니다.

옵션:

• --input: 에이전트에게 보낼 입력 메시지 (--resume이 설정된 경우 선택 사항이며, 그렇지 않으면 필수)
• --conversation: 대화 ID (Conversation ID) (선택 사항, 제공되지 않으면 UUID를 생성하거나, 존재하면 재개함)
• --agent: 사용할 에이전트 ID (Agent ID) (선택 사항, 기본값은 planner)
• --server: gRPC 컨트롤러 서버 주소 (선택 사항. 제공되지 않으면 로컬 내장 AX 서버로 실행)
• --config: YAML 설정 파일 경로 (로컬 내장 AX 서버 사용 시에만 사용됨, 기본값: "ax.yaml")
• --resume: 입력 없이 대화를 재개 (선택 사항, --input과 상호 배타적)
• --last-seq: 재개를 위해 클라이언트가 마지막으로 확인한 시퀀스 번호 (Last sequence number) (선택 사항). 서버는 클라이언트가 연결 끊김 이후에 따라잡을 수 있도록 이후의 모든 이벤트를 다시 재생(replay)합니다.

예시:

# 새로운 실행 수행
ax exec --input "Hello agents!"

...

Serve

ax serve [--config <path>]

YAML 설정 파일을 사용하여 컨트롤러를 gRPC 서버로 시작합니다.

옵션:

• --config: YAML 설정 파일 경로 (기본값: "ax.yaml")

설정 파일 예시 (ax.yaml):

server:
  address: ":8494"

...

예시:

# 기본 설정(ax.yaml)으로 서버 시작
ax serve

...

Fork

특정 체크포인트(또는 최신 상태)로부터 기존의 에이전트 이벤트 로그 (agentic event log)를 새로운 이벤트 로그로 포크(Fork)합니다.

ax fork \
    --src-conversation <id> \
    --dest-conversation <id> \
...

옵션:

• --src-conversation: 포크(fork)할 소스 대화 ID (필수)
• --dest-conversation: 새로운 이벤트 로그를 위한 대상 대화 ID (필수)
• --src-seq: 포크할 시퀀스 번호 (선택 사항, 기본값은 최신 상태). 소스 대화에 존재하는 시퀀스여야 합니다.
• --server: gRPC 컨트롤러 서버 주소 (기본값: "localhost:8494")

예시:

# 최신 상태에서 새로운 대화로 포크
ax fork --src-conversation 38460323-9a78-41cb-8991-022b0ff2c19c \
        --dest-conversation e5e26e38-53a2-4f22-b1cb-ae867357df83
...

Trace (추적)

이벤트 로그에서 직접 데이터를 가져와 에이전트 실행 (agentic execution)의 추적 과정을 Web UI에서 시각화합니다.

ax trace --conversation <id> [--addr <address>] [--config <file>]

이 명령은 실행 로그를 파싱하고 로컬 웹 서버를 구동하며, 브라우저에서 자동으로 해당 서버를 엽니다.

옵션:

• --addr: 대기할 서버 주소 (선택 사항, 기본값은 "localhost:8080")
• --config: YAML 설정 파일 경로 (선택 사항, 기본값은 "ax.yaml")

예시:

# 기본 서버 localhost:8080에서 추적
ax trace --conversation 1a6e0b29-87c2-4af0-81ac-0c73bf8fa293

...

Gemini Agent

AX에는 주어진 프롬프트(prompt)를 기반으로 텍스트를 생성할 수 있는 내장 Gemini 에이전트가 포함되어 있습니다. 이 에이전트는 gemini로 등록되어 있으며, 독립형 에이전트로 트리거하거나 커스텀 에이전트 구현체에서 사용할 수 있습니다.

ax exec --agent gemini \
  --input "Hello, how are you?"

인증 (Authentication)

Gemini 에이전트는 Google AI Studio 또는 Vertex AI를 사용한 인증을 지원합니다:

# AI Studio API 키 기반 인증.
export GEMINI_API_KEY="your-api-key"

...

Extensions (확장)

Skills (기술)

AX는 에이전트 기술 (Agent Skills)에 대한 내장 지원을 포함합니다. 자세한 내용은 Skills를 참조하세요.

Bash Tool

내장된 플래너(planner)는 범용 셸 명령어를 실행할 수 있는 bash 도구를 갖추고 있습니다. 이 도구는 사용자의 운영 체제에 자동으로 적응합니다.

안전과 제어를 위해, bash 도구에 의해 시작된 모든 실행은 실행 전 확인 흐름(confirmation flow)을 통해 사용자의 명시적인 승인을 필요로 합니다.

Custom Agents (커스텀 에이전트)

AX는 사용자의 에이전트를 런타임(runtime)에 가져오는 여러 가지 방법을 지원합니다.

Remote agents (원격 에이전트)

원격 에이전트는 AX 컨트롤러 외부에서 실행되며 프로토콜 경계(protocol boundary)를 통해 호출됩니다.

• Remote Agent는 AX의 네이티브 AgentService를 직접 구현합니다.
• ADK Agent (Python)는 Google ADK 에이전트를 원격 에이전트로 실행합니다.
• A2A Agent는 AX의 A2A 브릿지를 통해 A2A 프로토콜을 사용하는 에이전트들을 연결합니다.
• Colab Agents (Experimental)는 원격 Google Colab 세션에서 Python 스크립트 또는 노트북을 실행합니다.

AX는 재개 가능한 스트리밍(resumable streaming) 및 에이전트 통신 프로토콜을 활발히 개발 중임을 유의하십시오. 이러한 인터페이스는 안정적인 릴리스(stable release) 전에 변경될 수 있습니다.

AX 네이티브 원격 에이전트를 구현하는 경우, proto/ax.proto의 AgentService를 참조하십시오.

AX가 아닌 것은 무엇인가요?

• 관리형 서비스(managed service)가 아닙니다. AX는 셀프 호스팅(self-hosted) 방식이며 관리형 서비스가 아닙니다. 저희는 사용자가 자신의 Kubernetes 클러스터에 AX를 쉽게 배포하고 운영할 수 있도록 하는 것을 목표로 합니다.
• 에이전트 프레임워크(agentic framework)가 아닙니다. AX는 에이전트를 구축하는 데 사용되는 프레임워크에 구애받지 않습니다(agnostic). 저희는 다른 프레임워크 제작자들(예: ADK)과 협력하여 이들과의 쉬운 통합을 제공하기 위해 노력하고 있습니다.
• Antigravity와 같은 특정 코딩 에이전트와 같은 특정 하네스(harness)가 아닙니다. AX는 하네스 주변의 서빙 레이어(serving layer)를 제공하며 하네스 구현 방식에 구애받지 않습니다. 곧 사용자가 자신의 하네스를 가져올 수 있도록 허용할 예정입니다.
• 특정 모델 전용 컨트롤러가 아닙니다. AX는 사용되는 모델에 구애받지 않습니다.

Roadmap (로드맵)

다음은 향후 기능 및 계획된 변경 사항에 대한 개요입니다:

1. 내장형 하네스 (harness)로서의 Antigravity
2. BYOH (Bring Your Own Harness) 지원
3. 서브에이전트 (subagents)의 일시 중단 및 재개 (suspension/resumption) 기능 활성화
4. 서브에이전트 내 도구 호출 승인 (tool call approvals) 지원
5. 재개 프로토콜 (resumption protocols) 개선

Contributing (기여하기)

이 프로젝트에 기여하는 방법에 대한 지침은 CONTRIBUTING.md 가이드를 참조해 주세요.

현재 대대적인 아키텍처 재설계 (architectural redesign)를 진행 중이며, 외부 기여는 일시적으로 중단된 상태입니다.
하지만 그동안 버그를 보고하거나 기능 요청 (feature requests)을 보내주시는 것을 적극 권장합니다.

Acknowledgements (감사의 글)

AX에 큰 영향을 준 분산 하네스 (distributed harnesses) 분야의 초기 연구를 수행한 Google DeepMind에 감사드립니다.
격리 (isolation), 재개 (resumption) 및 작업 스케줄링 (job scheduling)과 관련하여 깊은 기여를 해준 Google Kubernetes Engine 팀에 감사드립니다.

License (라이선스)

Apache 2.0