Playground Agent

게시하기 전에, 에이전트는 Playground 기능을 사용하여 테스트해야 합니다. Playground는 샌드박스 환경에서 에이전트와 상호작용하고, MCP 서버 연결을 확인하며, Skill을 테스트하고, 모든 것이 예상대로 작동하는지 확인할 수 있게 해줍니다.

에이전트 Playground는 채팅 기반 테스트 인터페이스를 제공하며, 여기서 다음을 수행할 수 있습니다.

• 에이전트에게 메시지를 보내고 응답을 검토합니다.
• MCP 서버(커넥터)에 연결하고 인증합니다.
• 에이전트에 연결된 Skill을 선택하고 테스트합니다.
• 연결된 MCP 서버에서 도구 가용성을 확인합니다.
• 커넥터 및 Skill 구성을 관리합니다.

Playground 접근하기

1. 디자인 캔버스에서 AI 에이전트를 엽니다.
2. Playground 버튼을 클릭하여 테스트 인터페이스를 시작합니다.
3. Playground가 다음과 함께 열립니다.

   • 채팅 영역 (중앙): 에이전트와 상호작용하는 주요 대화 인터페이스입니다.

   • 우측 패널: Todos, Context, 및 Connectors 섹션을 표시합니다.

   • 입력 툴 바 (하단): 파일 추가, 커넥터 선택 및 Skill 선택 옵션입니다.

MCP 서버 인증하기

에이전트가 OAuth 인증이 필요한 MCP 서버를 사용할 때, 테스트 전에 인증해야 합니다.

단계 1: 인증되지 않은 MCP 서버 처리하기

MCP 서버가 아직 인증되지 않은 경우, 대화 상자가 나타납니다.

• 제목: "Unauthenticated MCP Servers"
• 메시지: "401 Not authenticated for below MCP Servers:"
• 인증되지 않은 서버 목록이 표시됩니다 (예: "ZCP Alert MCP").
• 인증하려는 서버 옆의 Connect를 클릭합니다.

2단계: 애플리케이션 승인

Connect를 클릭하면 브라우저 창이 Application Access Request 페이지로 열립니다.

• Application name: 접근을 요청하는 MCP 클라이언트입니다 (예: "NPO MCP Client").
• Server name: 접근 중인 MCP 서버입니다 (예: "zcp-alert-mcp-kks").
• Callback URL: 자격 증명 목적지 URL이 확인을 위해 표시합니다.
• 접근 요청 세부 정보를 주의 깊게 검토합니다.
• 권한을 부여하려면 Allow Access를 클릭하거나 거부하려면 Deny를 클릭하면 됩니다.
• 필요시 추가 정보를 보려면 Advanced Details을 확장합니다.

3단계: 인증 확인

인증이 성공적으로 완료되면 확인 페이지가 나타납니다.

• Title: "Authentication Complete"

• Message: "OAuth authentication completed successfully. You may close this window."

• User: 인증된 사용자 ID가 표시됩니다.

• Server: 연결된 백엔드 서버 이름이 표시됩니다.

• Playground로 돌아가려면 Close을 클릭합니다.

Note: 인증이 성공적으로 완료된 후 커넥터 상태 표시기가 빨간색(연결 끊김)에서 초록색(연결됨)으로 변경됩니다.

커넥터 사용하기

커넥터는 에이전트에 도구를 제공하는 MCP 서버입니다.

채팅에서 커넥터 선택하기

1. Playground 하단의 + 버튼이나 입력 영역을 클릭합니다.
2. 메뉴에서 Connectors를 선택합니다.
3. 하위 메뉴에 모든 사용 가능한 커넥터가 표시됩니다 (예: "ZCP Alert MCP").
4. 현재 대화에 대해 커넥터를 활성화하려면 커넥터를 클릭합니다.
5. Manage connectors를 클릭하여 고급 설정을 위해 Customize 패널을 엽니다.

커넥터 상태 표시기

각 커넥터는 상태 표시기를 보여줍니다.

• 빨간 점: 연결되지 않음 / 인증 필요.
• 초록 점: 연결됨 및 사용 준비 완료.
• 링크 아이콘: 클릭하여 연결을 시작하거나 재인증.

Skill 사용하기

Skill은 에이전트의 기능을 확장하는 재사용 가능한 작업 구성 요소입니다.

채팅에서 Skill 선택하기

1. Playground 하단의 + 버튼이나 입력 영역을 클릭합니다.
2. 메뉴에서 Skills를 선택합니다.
3. 하위 메뉴에 모든 사용 가능한 Skill이 표시됩니다 (예: "new skill edit 28.4", "skill-creator2").
4. Skill을 클릭하여 현재 대화에 첨부합니다.
5. Skill 구성을 위해 Manage skills를 클릭하여 Customize 패널을 엽니다.

Customize 패널

Customize 패널을 통해 커넥터와 Skill을 자세히 관리할 수 있습니다.

커넥터 관리하기

1. 커넥터 하위 메뉴에서 Manage connectors를 클릭하거나 Customize 패널을 직접 엽니다.
2. Connectors 탭에는 다음이 표시됩니다.
   • 좌측 패널: 연결 상태와 함께 모든 MCP 서버 목록.
   • 우측 패널: 선택한 MCP 서버에서 사용할 수 있는 도구.
3. 목록에서 MCP 서버를 선택하여 사용 가능한 도구를 봅니다.
4. "No tools available"이 표시되면 MCP 서버가 필요할 수 있습니다.
   • 인증 (연결하려면 링크 아이콘을 클릭).
   • 서버 측 도구 구성.
   • 백엔드가 실행 중이고 접근 가능한지 확인.

Skill 관리하기

1. Skills 하위 메뉴에서 Manage skills를 클릭하거나 Customize 패널에서 Skills 탭으로 전환합니다.
2. Skills 탭에는 다음이 표시됩니다.
   • 좌측 패널: 구성된 모든 Skill의 목록 (예: "Docs Deployer", "Docs Updator").
   • 우측 패널: 설명, SKILL.md 내용 및 첨부 파일을 포함한 Skill 세부정보.
3. Skill을 선택하여 다음을 확인합니다.

• Description: Skill의 목적에 대한 간략한 개요.

• SKILL.md: 자세한 지침 및 워크플로 정의.

• Files: 관련 파일 및 리소스.

에이전트 테스팅

메시지 전송

1. 채팅 영역 하단의 입력 필드에 메시지를 입력합니다.

2. Send 버튼(화살표 아이콘)을 클릭하거나 Enter 키를 누릅니다.

3. 에이전트는 구성된 LLM, 커넥터 및 Skill을 사용하여 메시지를 처리합니다.

4. 응답이 채팅 영역에 나타납니다.

에이전트가 인간의 개입이 필요한 도구를 호출하면, 채팅은 아래 이미지와 같이 인간의 결정을 기다리는 개입 상태로 보입니다.

파일 및 사진 추가

1. Playground 하단의 + 버튼을 클릭합니다.
2. Add photos & files을 선택합니다.
3. 대화의 맥락으로 포함할 파일을 업로드합니다.

오른쪽 패널 모니터링

오른쪽 패널은 실시간 상태를 제공합니다.

섹션	설명
Todos	에이전트가 추적 중인 작업 항목을 표시합니다. 존재하지 않으면 "찾을 수 없음"이라고 표시됩니다.
Context	에이전트가 사용 중인 컨텍스트 데이터를 보여줍니다. 존재하지 않으면 "찾을 수 없음"이라고 표시됩니다.
Connectors	연결된 MCP 서버와 그 상태 표시기를 나열합니다.

Troubleshooting

MCP 서버에 "No tools available" 표시

• MCP 서버가 인증되었는지 확인합니다 (상태는 녹색이어야 합니다).
• 백엔드 서버가 실행 중이고 접근 가능한지 확인합니다.
• MCP 서버 프로파일에 도구가 올바르게 구성되어 있는지 확인합니다.
• MCP 서버의 연결을 끊었다가 다시 연결합니다.

인증 실패 (401 오류)

• OAuth 자격 증명 (클라이언트 ID, 클라이언트 비밀)이 올바른지 확인합니다.
• OAuth 공급자 URL에 접근할 수 있는지 확인합니다.
• 사용자 계정이 MCP 서버에 접근할 수 있는 권한이 있는지 확인합니다.
• OAuth 흐름을 다시 시작하기 위해 Connect을 다시 클릭합니다.

인증 후 커넥터 상태가 빨간색으로 유지됨

• Playground 페이지를 새로 고칩니다.
• 인증 콜백 URL이 올바르게 구성되어 있는지 확인합니다.
• MCP 서버 엔드포인트에 대한 네트워크 연결을 확인합니다.

---

모범 사례

• 단계적으로 테스트: 기본 채팅을 먼저 테스트한 후, 커넥터와 Skill을 하나씩 추가합니다.
• 먼저 인증 확인: 도구 의존 기능을 테스트하기 전에 모든 MCP 서버가 정상 상태(녹색)를 표시하는지 확인합니다.
• 도구 사용 가능 여부 확인: Customize 패널을 사용하여 연결된 MCP 서버에서 도구가 제대로 로드되었는지 확인합니다.
• Skill 정의 검토: Skill 탭을 열어 Skill.md 지침이 예상 동작과 일치하는지 확인합니다.
• 새 채팅 시작: 테스트 시나리오를 전환할 때 대화 컨텍스트를 초기화하기 위해 + New Chat을 클릭합니다.
• 배포 전 테스트: 프로덕션에 배포하기 전에 Playground에서 에이전트 동작을 충분히 검증합니다.