agentregistry 사용

cloud2000·2026년 4월 12일

CLI 설치 및 빌드/배포

MCP 서버, AI 에이전트, 스킬을 한 곳에서 관리하는 GitHub 오픈소스 플랫폼
아직 v0.3.3이 최신 버전이라 완성도가 떨이짐

arctl cli 설치

curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash

arctl daemon start	// daemon 시작
arctl daemon status // daemon 상태 조회
arctl version

docker로 상태 확인

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}"
CONTAINER ID   NAMES                     STATUS
463abb4207da   agentregistry-server      Up 3 minutes
eae9b8972f32   agent-registry-postgres   Up 3 minutes (healthy)

전체 흐름

init → add-mcp / add-skill → build → run (테스트) → publish → deploy

1단계: Agent 개발 (init + 구성)

스캐폴딩 생성

arctl agent init adk python dacAgent --model-provider Anthropic --model-name claude-sonnet-4-6

생성되는 디렉터리 구조:

dacAgent
├── agent.yaml		# 에이전트 메타데이터 및 구성
├── dacAgent
│   ├── __init__.py
│   ├── agent-card.json
│   ├── agent.py
│   ├── mcp_tools.py
│   └── prompts_loader.py
├── docker-compose.yaml
├── Dockerfile		# docker image 생성을 위한 기본 dockerfile
├── pyproject.toml
└── README.md

agent.yaml 편집

agentName: dacAgent
#image: ghcr.io/dacAgent:latest
image: docker.io/cloud20000/dacAgent:v0.1		# docker image 경로
language: python
framework: adk
modelProvider: anthropic						# LLM provider 이름
modelName: claude-sonnet-4-6					# LLM model 이름
description: "To test dac agent"
updatedAt: 2026-04-12T18:50:28.63958+09:00

2단계: 빌드

# Docker 이미지로 빌드 & docker.io로 push. docker login 사전 필수
arctl agent build ./dacAgent --push

3단계: 로컬 테스트 (run)

# 기본 실행
export ANTHROPIC_API_KEY="sk-ant-..."
arctl agent run ./dacAgent
Running agent from local directory: ./dacAgent
✓ Docker containers started
Waiting for agent to be ready...
Chat with dacAgent (session ctx-03623006-64d9-4c7f-bdf1-56c6e188f73b)     




> Type a message (Enter to send)

# 환경변수 전달
arctl agent run ./dacAgent --env ANTHROPIC_API_KEY=sk-ant-xxx

# 상세 출력 (디버그)
arctl agent run ./dacAgent -v

4단계: Registry에 업로드 (publish)

# http://localhost:12121 에 publish
arctl agent publish .

# http://agentregistry.local에 publish
arctl --registry-url http://agentregistry.local agent publish ./dacAgent --overwrite

참고: agentregistry는 이미지 자체를 저장하지 않고 이미지 위치에 대한 카탈로그 엔트리(포인터)를 저장합니다.
실제 이미지는 Docker Hub 또는 내부 레지스트리에 저장됩니다.

MCP 서버 추가

arctl agent add-mcp time-tool --mcp time-mcp

Skill 추가

arctl agent add-skill time-agent --skill time-knowledge

Prompt 추가

arctl agent add-prompt time-agent --prompt time-prompt

상태 확인

arctl agent list              # 에이전트 목록
arctl agent show my-yms-agent # 상세 정보
arctl deployments list        # 배포 상태

5단계: 배포 (deploy)

로컬 배포

arctl deployments create my-yms-agent \
  --env ANTHROPIC_API_KEY=sk-ant-xxx

Kubernetes 배포

arctl deployments create my-yms-agent \
  --target kubernetes \
  --namespace ai-agents \
  --env ANTHROPIC_API_KEY=sk-ant-xxx

배포 확인 및 삭제

arctl deployments list
arctl deployments show my-yms-agent
arctl deployments delete my-yms-agent

IDE 연동

arctl configure claude    # Claude Desktop
arctl configure cursor    # Cursor
arctl configure vscode    # VS Code

Air-Gapped 환경 팁

# 원격 레지스트리 사용 시 API 엔드포인트 지정
arctl --registry-url http://YOUR-HOST:12121 agent publish .

# 내부 Container Registry 사용
arctl agent publish . \
  --docker-url registry.internal.company.com/utcloud \
  --push

전체 명령어 요약

단계	명령어
초기화	`arctl agent init <name>`
MCP 추가	`arctl agent add-mcp <name> --mcp <mcp>`
Skill 추가	`arctl agent add-skill <name> --skill <skill>`
Prompt 추가	`arctl agent add-prompt <name> --prompt <prompt>`
빌드	`arctl agent build .`
로컬 실행	`arctl agent run <name>`
목록 조회	`arctl agent list`
상세 확인	`arctl agent show <name>`
업로드	`arctl agent publish . --docker-url <url> --push`
배포 생성	`arctl deployments create <name>`
배포 목록	`arctl deployments list`
배포 삭제	`arctl deployments delete <name>`
에이전트 삭제	`arctl agent delete <name>`