에이전트 배포

에이전트 배포 (Agent Distribution)

OCI 호환 레지스트리를 통해 에이전트를 패키징하고 공유하며 실행해요 — 컨테이너 이미지처럼 말이죠.

출처: 문서

본문

개요 (Overview)

Docker Agent 에이전트는 어떤 OCI 호환 레지스트리(Docker Hub, GitHub Container Registry 등)로든 push할 수 있고 어디서든 pull/run할 수 있어요. 이렇게 하면 에이전트를 Docker 이미지처럼 쉽게 공유할 수 있어요.

Tip 배포와 관련된 CLI 명령은 CLI Reference (docker agent share push, docker agent share pull, docker agent alias)를 참고하세요.

에이전트 푸시 (Pushing Agents)

# Push to Docker Hub
$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest

# Push to GitHub Container Registry
$ docker agent share push ./agent.yaml ghcr.io/username/my-agent:v1.0

에이전트 풀 (Pulling Agents)

# Pull an agent
$ docker agent share pull docker.io/username/my-agent:latest

# Pull from Docker Hub shorthand
$ docker agent share pull myorg/agent:tag

레지스트리에서 실행 (Running from a Registry)

먼저 풀하지 않고 레지스트리에서 직접 에이전트를 실행해요:

# Run directly from Docker Hub
$ docker agent run docker.io/username/my-agent:latest

# Docker Hub shorthand (docker.io is implied)
$ docker agent run myorg/agent:tag

# Run with a specific agent from a multi-agent config
$ docker agent run docker.io/username/dev-team:latest -a developer

하위 에이전트로 사용 (Using as Sub-Agents)

레지스트리 에이전트는 다중 에이전트 구성에서 직접 하위 에이전트로 사용할 수 있어요 — 로컬에 정의할 필요가 없죠:

agents:
  root:
    model: openai/gpt-5
    description: Coordinator
    instruction: Delegate tasks to the right sub-agent.
    sub_agents:
      - myorg/agent:tag # auto-named "agent"
      - my_reviewer:myorg/reviewer # explicitly named "my_reviewer"

외부 하위 에이전트는 마지막 경로 세그먼트 뒤에 자동으로 이름이 붙어요. name:reference 구문을 사용하면 커스텀 이름을 줄 수 있어요.

태그 참조는 매 docker agent run 마다 레지스트리에서 확인되어, 시작 시 하위 에이전트당 네트워크 왕복이 추가돼요. 대신 다이제스트(myorg/agent@sha256:…)로 고정하면 캐시에서 제공받을 수 있어요.

자세한 내용은 Pin external sub-agents to a digest와 External Sub-Agents를 참고하세요.

별칭과 함께 사용 (Using with Aliases)

편리한 접근을 위해 OCI 참조와 별칭을 결합해요:

# Create an alias for a registry agent
$ docker agent alias add coder myorg/coder --yolo

# Now just run
$ docker agent run coder

API 서버와 함께 사용 (Using with API Server)

API 서버는 자동 새로고침과 함께 OCI 참조를 지원해요:

# Start API from registry, auto-pull every 10 minutes
$ docker agent serve api docker.io/username/agent:latest --pull-interval 10

비공개 저장소 (Private Repositories)

Docker Agent는 인증을 요구하는 비공개 GitHub 저장소와 레지스트리에서 풀하는 것을 지원해요. 표준 Docker 로그인 또는 GitHub 인증을 사용해요:

# Login to a registry
$ docker login docker.io

# Now push/pull works with private repos
$ docker agent share push ./agent.yaml docker.io/myorg/private-agent:latest
$ docker agent run docker.io/myorg/private-agent:latest

Note Docker 인증 (Docker authentication) docker.com 또는 *.docker.com HTTPS URL(예: desktop.docker.com)에서 에이전트를 풀하거나 실행할 때, Docker Agent는 인증을 위해 Docker 토큰을 자동으로 전달해요. Docker Desktop이 실행되고 로그인되어 있으면 그 토큰을 사용하고, 그렇지 않으면 Docker Agent가 docker login 으로 저장된 액세스 토큰을 새 Docker 토큰으로 교환해요. 어느 경우든 docker login(또는 Docker Desktop 로그인) 외에 별도 로그인 단계는 필요 없어요.

참고: docker.io(표준 Docker Hub 레지스트리 도메인)는 별개의 도메인이며 자동 토큰 전달 대상이 아니에요. docker.io 나 registry-1.docker.io 에서 풀한 에이전트는 비공개 저장소에 대해 여전히 docker login docker.io 가 필요해요.

Note 문제 해결 (Troubleshooting) push/pull에 문제가 있나요? 일반적인 레지스트리 문제는 Troubleshooting을 참고하세요.

로컬 개발 (Local Development)

로컬 개발과 테스트를 위해 레지스트리 없이 로컬 HTTP 서버에서 에이전트를 직접 실행할 수 있어요:

# Serve an agent config locally
$ python3 -m http.server 8080

# Run it directly via HTTP
$ docker agent run http://localhost:8080/agent.yaml
$ docker agent run http://127.0.0.1:8080/agent.yaml

이는 레지스트리에 push하기 전에 로컬 개발 서버에서 제공하는 에이전트 구성을 반복(iterate)하는 데 유용해요. localhost 와 127.0.0.1 주소 모두 평문 http:// URL로 지원돼요.

에이전트 배포