계획 수립 & 실행¶

스쿼드에 요청을 제출하면 플래너 에이전트가 구조화된 플랜을 생성하고, 사용자가 검토 및 승인한 후, 의존성을 고려한 웨이브 단위로 태스크를 실행합니다.

요청 제출¶

스쿼드 모니터링 대시보드를 열고 입력 필드에 요청을 입력합니다. 달성하고자 하는 바를 자연어로 설명하세요:

"CRUD 엔드포인트, 입력 유효성 검사, 단위 테스트가 포함된 사용자 관리 REST API를 구축하세요."

플래너가 수동 검토 없이 좋은 플랜을 만들 것이라고 신뢰하는 경우 선택적으로 자동 승인을 토글할 수 있습니다.

실행 전 확인¶

플래너가 돌기 전에 스쿼드는 이번 실행이 제대로 돌 수 있는지부터 확인하는데, 플래너와 모든 에이전트, 워크스페이스, 컨테이너 런타임이 대상입니다. 아무 문제가 없으면 요청은 곧바로 플래너로 넘어가고, 문제가 있으면 요청은 실행 전 확인 카드에서 기다립니다. 카드에는 문제마다 관련된 에이전트와 모델, 원인을 담은 한 문장, 해결 버튼이 나오고, 확인 결과의 원문은 자세히 아래에 남습니다.

실행을 막는 문제는 오류로 표시되고, 카드에는 다시 확인과 요청을 입력창으로 되돌리는 취소가 나옵니다. 경고만 남으면 그대로 실행도 함께 나오죠. 에이전트 설정을 바꾸거나 카드에서 모델을 실행하면 카드가 알아서 다시 확인합니다.

서버도 실행이 시작되는 모든 경로에서 같은 확인을 거치는데, 새 요청, 플랜 승인, 일시정지된 실행의 재개, 실패한 태스크 다시 실행이 모두 해당합니다. 실행을 막는 문제가 있으면 어떤 작업도 하기 전에 거부하므로, 플랜이 승인을 기다리는 동안 모델이 멈췄다면 태스크가 모두 실패하는 대신 같은 문제 목록과 함께 승인이 거부됩니다. 경고는 실행을 거부하지 않고, 라우터가 응답하지 않는 경우도 거부가 아닌 경고로 처리합니다. 다시 시작 중인 라우터 때문에 멀쩡한 스쿼드가 막히면 안 되기 때문이죠.

계획 수립 단계¶

플래너 에이전트가 요청을 받아 다음을 포함하는 플랜을 생성합니다:

• 제목 — 계획된 작업의 간결한 요약
• 태스크 — 각각 다음을 포함하는 개별 작업 단위:
  • 제목과 설명
  • 할당된 에이전트
  • 다른 태스크에 대한 의존성
  • 우선순위 수준 (낮음, 보통, 높음, 긴급)

graph LR
    T1[API 스키마 설계] --> T2[엔드포인트 구현]
    T1 --> T3[유효성 검사 작성]
    T2 --> T4[단위 테스트 작성]
    T3 --> T4
    T4 --> T5[코드 리뷰]

플래너가 플랜을 만들지 못할 때¶

추론 라우터가 실행 중이 아니거나, 플래너 에이전트에 모델이 없거나, 응답이 출력 한도에서 잘렸거나, 태스크를 하나도 만들지 않고 답했거나, 모델 호출이 실패해 플래너가 플랜을 만들지 못하면 스쿼드는 아무것도 시작하지 않습니다. 플랜 카드에는 계획을 만들지 못함과 함께 이유가 표시되고, 이유를 고칠 수 있는 설정(플래너 모델은 에이전트 설정 열기, 모델 실행은 모델 페이지 열기)과 두 가지 선택지가 함께 나옵니다. 그대로 실행은 각 에이전트에게 요청 전체를 주는 대체 플랜을 실행하고, 실행 취소는 실행을 끝내죠. 대체 플랜은 아무도 고른 적이 없는 플랜이라 자동 승인이 켜져 있어도 마찬가지로 기다립니다. 원인을 고친 다음 거부를 누르면 플래너가 새 플랜을 만드는데, 새 플랜도 승인을 기다립니다.

플랜 승인¶

자동 승인이 활성화되지 않은 경우, 계획 승인 대화 상자에서 플랜이 검토용으로 제시됩니다. 확인할 수 있는 항목:

• 설명이 포함된 전체 태스크 목록
• 에이전트 할당
• 의존성 그래프
• 예상 복잡도

승인 및 실행을 클릭하면 실행이 시작되고, 거부를 클릭하면 플랜이 폐기됩니다. 선택적으로 플래너가 다시 시도할 수 있도록 피드백을 제공할 수 있습니다.

플랜은 승인할 때까지 기다리며, 만료되거나 저절로 취소되지 않습니다. 카드에는 얼마나 기다렸는지가 표시되고, 5분이 지나면 플랜이 만료되지 않는다는 안내와 실행 취소가 함께 나옵니다. 계획 수립에도 따로 정해진 시간 제한이 없는데, 큰 모델은 플래너 호출 한 번에 몇 분이 걸리기도 하기 때문이죠. 플래너가 일하는 동안 채팅에는 경과 시간이 표시되고, 1분 30초가 지나면 아직 계획을 세우는 중이라는 안내와 실행 취소가 나옵니다. 앱이 실행 상태를 읽지 못하면 실행이 계속 진행 중인 것처럼 보이는 대신, 채팅에 오류와 함께 다시 시도와 닫기가 표시됩니다.

승인 전에 플랜 편집하기¶

계획 수정을 누르면 태스크 목록이 편집기로 바뀝니다. 태스크의 제목과 설명을 고치고, 스쿼드의 다른 에이전트에게 재할당하고, 우선순위를 바꾸고, 태스크를 제거하거나 직접 추가할 수 있습니다.

직접 추가한 태스크는 ID를 가지며, 행 안에 표시되고 입력하는 제목에서 파생됩니다. 다른 태스크는 이 ID로 해당 태스크에 의존하므로 ID 필드는 편집할 수 있습니다. ID에는 ASCII 영문자, 숫자, 하이픈만 쓸 수 있고 최대 128바이트이며, index나 CON 같은 Windows 예약 장치 이름은 쓸 수 없습니다. 스쿼드 보드가 각 태스크를 자신의 index.json 옆에 <id>.json으로 쓰기 때문입니다. 필드를 비워 두면 서버가 ID를 만들며, 이 경우 어떤 태스크도 그 태스크에 의존할 수 없습니다.

의존성은 직접 입력하지 않고 다른 행에서 선택합니다. 따라서 직접 추가한 태스크가 역시 직접 추가한 다른 태스크에 순서와 무관하게 의존할 수 있습니다. ID가 충돌하거나(대소문자만 다른 경우 포함) 의존성이 순환을 이루는 플랜은 편집기가 문제가 되는 행을 지목하며 거부하고, 편집된 플랜이 도착하면 서버도 같은 규칙을 적용합니다.

웨이브 실행¶

승인되면 태스크는 의존성에 따라 웨이브로 구성됩니다:

gantt
    title 실행 웨이브
    dateFormat X
    axisFormat %s

    section 웨이브 1
    API 스키마 설계        :0, 1
    section 웨이브 2
    엔드포인트 구현        :1, 2
    유효성 검사 작성       :1, 2
    section 웨이브 3
    단위 테스트 작성       :2, 3
    section 웨이브 4
    코드 리뷰             :3, 4

• 같은 웨이브 내 태스크는 병렬로 실행됩니다
• 다음 웨이브는 이전 웨이브의 모든 태스크가 완료된 후에만 시작됩니다
• 태스크가 실패하면 이후 웨이브의 의존 태스크는 자동으로 건너뜁니다
• 도구 호출 라운드를 모두 사용한 태스크는 그때까지의 내용으로 답하므로 뒤의 태스크는 그대로 실행되지만, 완료되지 않은 답변으로 표시되고 실행은 부분 완료로 끝납니다
• 스쿼드의 명령 실행이 꺼져 있을 때 모델이 명령이나 코드를 실행하려 한 태스크는 해당 호출만 거부되고 파일 작업으로 계속 진행되는데, 명령 실행 필요로 표시되고 실행은 부분 완료로 끝납니다. 명령 실행을 켜거나, 해당 작업을 폴더를 연결한 코워크 대화에서 실행하세요
• 출력 토큰 한도에서 잘린 응답이나 빈 응답은 태스크 결과로 치지 않고 태스크를 실패로 처리합니다
• 답하기 전에 생각하는 모델은 생각이 답할 자리까지 차지하지 않도록 응답에 컨텍스트 윈도우의 4분의 1 대신 절반을 사용합니다. 모델이 아직 생각하는 중에 한도에서 잘린 응답은 컨텍스트 윈도우가 허용하는 만큼 자리를 늘려 한 번 더 요청하고, 이 컴퓨터에서 실행하는 모델이면 생각을 끄고 요청합니다
• 출력 토큰 한도에서 잘린 도구 호출은 실행하지 않고, 에이전트에게 출력을 줄여 다시 호출하라고 알립니다

태스크가 받는 컨텍스트¶

각 태스크는 에이전트 모델의 크기에 맞춘 컨텍스트로 시작하므로, 컨텍스트 윈도우가 8K~32K인 모델도 긴 실행의 모든 태스크를 처리할 수 있습니다.

• 에이전트의 시스템 프롬프트와 태스크 본문.
• 태스크가 의존하는 태스크의 결과. 결과 전체가 모델 컨텍스트 윈도우의 4분의 1을 넘지 않습니다. 이보다 긴 결과는 앞부분과 뒷부분, 생략된 분량 안내와 함께 전달되고, 전체 내용은 워크스페이스의 artifacts/tool-results/에 저장되어 에이전트가 read_tool_result 도구로 읽을 수 있습니다.
• 짧은 배경 정보. 같은 실행에서 해당 에이전트가 앞서 끝낸 태스크가 한 줄씩, 에이전트 채팅에서 나눈 대화의 최근 부분이 포함됩니다.

해당 에이전트의 이전 태스크 결과와 나머지 채팅 기록은 다시 보내지 않습니다. 태스크 안에서는 도구 라운드마다 호출과 결과가 대화에 쌓입니다. 대화가 모델 윈도우의 약 4분의 3을 채우면 다음 모델 호출 전에 가장 오래된 라운드부터 줄어듭니다. 긴 결과는 안내 문구로 바뀌고, 에이전트가 쓴 파일 내용처럼 긴 인자는 앞부분만 남습니다. 가장 최근 라운드는 그대로 유지되며, 에이전트는 결과가 다시 필요하면 도구를 다시 실행합니다. 라운드가 줄어들면 실행 로그에 기록됩니다.

실행 라이프사이클¶

워크스페이스에 쓸 수 없는 실행은 시작하기 전에 경로를 담은 오류와 함께 거부됩니다(실행 전 확인 참고). 확인을 마친 뒤 첫 웨이브 전에 워크스페이스를 쓸 수 없게 되어 확인을 통과한 실행은 첫 웨이브 전에 실패하는데, 이런 실행은 워크스페이스의 실행 기록에도 기록을 쓸 수 없으므로 실행 탭이 앱이나 서버를 다시 시작할 때까지 해당 이유와 함께 목록에 남겨 둡니다.

진행 상황 모니터링¶

스쿼드 모니터링 대시보드에서 실시간 실행 진행 상황을 보여 줍니다:

• 현재 웨이브와 전체 웨이브 수
• 태스크 수 — 대기, 실행 중, 완료, 실패, 건너뜀
• 에이전트별 상태 — 활성, 유휴, 또는 오류 상태인 에이전트
• 토큰 사용량 — 에이전트별 및 전체 실시간 소비량
• 활동 피드 — 이벤트의 시간순 로그 (에이전트 시작, 태스크 완료, 메모리 업데이트 등)
• 실시간 작업 요약 티커 — 채팅 영역 하단의 소형 바에 계획 수립 및 실행 단계 동안 플래너 또는 활성 에이전트가 현재 수행 중인 작업의 한 줄 요약이 지속적으로 업데이트됩니다. × 버튼을 클릭하여 닫을 수 있습니다.

백엔드 대기¶

프로세스 내 에이전트의 모델 요청 중 continuum-router에서 사용할 수 있는 정상 백엔드가 잠시 사라지면, 현재 스쿼드 실행은 일시정지되고 다음 시도 번호와 전체 시도 횟수, 대기 시간이 경고 배너에 표시됩니다. 로컬 모델을 로드하거나 다시 로드하는 동안 이런 상황이 생깁니다. 같은 모델 요청을 1초, 2초, 4초, 8초 뒤에, 그다음부터는 15초마다 다시 보내며 모두 12회, 약 2분 동안 시도합니다. 기다리는 동안에도 이미 완료된 태스크 결과는 화면에 그대로 남습니다. 컨테이너를 다시 실행하면 외부 부수 효과가 반복될 수 있으므로 컨테이너 태스크는 한 번만 디스패치합니다.

이 자동 일시정지 상태에서는 재개 버튼이 숨겨집니다. 백엔드가 없는 상태나 안전한 대기 시간을 수동 재개로 건너뛸 수 없기 때문이고, 실행을 끝내는 취소는 계속 사용할 수 있습니다. 백엔드가 다시 준비되면 같은 실행이 자동으로 이어집니다. 기존 태스크 및 실행 제한 시간은 자동 재시도 중에도 계속 흐릅니다.

모든 시도가 실패해도 실행은 실패로 끝나지 않고 일시정지 상태로 남으며, 태스크는 보내던 요청을 유지한 채 대기합니다. 실행 카드에는 사용 가능한 백엔드 없음과 함께 모델 페이지 열기, 재개 버튼이 표시되고, 알림에도 같은 내용이 표시됩니다. 모델을 로드하거나 프로바이더를 확인한 뒤 재개를 누르면 같은 요청을 새 재시도 횟수로 다시 보내며, 완료된 태스크는 다시 실행되지 않습니다. 사용자의 재개를 기다리는 동안에는 다른 일시정지와 마찬가지로 실행 제한 시간이 흐르지 않습니다.

태스크나 실행이 실패했을 때¶

실패한 태스크와 작업을 마치지 못한 채 답한 태스크는 실행 카드와 실행 상세에서 무슨 일이 있었는지 설명됩니다. 제목과 원인을 담은 한 문장, 어느 설정을 어디서 바꿔야 하는지가 나오고, 열 수 있는 설정이 있으면 그 설정을 여는 버튼도 함께 나오죠. 백엔드가 보낸 원래 메시지는 자세히 아래에 남아 있습니다. 실행 요약은 태스크 개수가 아니라 첫 번째 문제로 시작하고, 실패한 실행의 채팅 메시지와 알림도 같은 설명을 사용합니다.

실패한 태스크 다시 실행¶

실패나 부분 완료로 끝난 실행은 실행 카드와 실행 탭에서 실패한 작업 다시 실행을 제공합니다. 다시 실행하면 실패했거나, 긴급 중지로 멈췄거나, 시작하지 못했거나, 작업을 마치지 못한 채 답한 태스크와 그 태스크에 의존하는 모든 태스크가 다시 실행되는데, 완료된 태스크는 결과를 그대로 두고 다시 실행하지 않으며 직접 건너뛴 태스크도 건너뛴 상태로 남습니다. 다시 실행해도 같은 실행이라 끝나면 실행 기록이 새 결과로 바뀌죠. 예산이 켜져 있다면 토큰 사용량은 이어서 쌓이고, 예산의 실행 시간 제한은 새로 시작합니다. 앱이 아직 보관 중인 실행만 다시 실행할 수 있으므로, 앱이나 서버를 다시 시작한 뒤에는 요청을 다시 보내세요.

실행 취소¶

언제든 취소를 클릭하여 현재 실행을 중단할 수 있습니다. 실행 중인 태스크는 종료되고 대기 중인 태스크는 취소됨으로 표시됩니다. 완료된 태스크 결과는 보존됩니다.

에이전트 채팅¶

에이전트 채팅을 통해 개별 에이전트와 직접 상호작용할 수도 있습니다:

• 스쿼드 내 모든 에이전트와 대화를 시작할 수 있습니다
• 메시지가 실시간으로 스트리밍됩니다
• 대화가 워크스페이스에 저장됩니다
• 대화별 토큰 사용량이 추적됩니다

채팅 턴은 스쿼드 태스크 실행 및 토론방 턴과 동일하게 백엔드에서 완전히 처리됩니다. 에이전트는 설정에 나열된 도구를 채팅 중에도 사용할 수 있고, 아래 범위 안에서 동작합니다.

이 기능은 임시 질문, 에이전트 동작 디버깅, 또는 정상적인 계획 수립 흐름 외부에서 추가 컨텍스트를 제공하는 데 유용합니다.

스쿼드 워크스페이스의 도구¶

경로를 받는 도구는 모두 스쿼드 워크스페이스 안에서 동작하는데, 채팅과 토론방, 실행 어디에서나 마찬가지입니다. 파일 읽기와 쓰기(read_file, write_file), 목록 확인과 검색(list_files, list_directory, search_files, search_content, diff_files), 폴더 만들기와 파일 이동, 삭제(create_directory, move_file, delete_file), 문서와 미디어 읽기(pdf_reader, csv_reader, json_query, image_info, image_to_base64, view_image, 데스크톱의 audio_transcribe)가 여기에 해당합니다.

• 상대 경로는 워크스페이스 루트를 기준으로 해석되고, 절대 경로는 워크스페이스 안을 가리킬 때만 사용할 수 있습니다.
• 워크스페이스를 벗어나는 경로는 사용할 상대 경로를 알려 주는 메시지와 함께 거부되는데, 워크스페이스 밖의 절대 경로와 .. 단계, 워크스페이스 밖을 가리키는 링크가 여기에 해당하죠. 이동은 원본과 대상을 모두 확인하고, 워크스페이스 폴더 자체는 삭제하거나 이동할 수 없습니다.
• search_content는 링크를 따라가지 않고, 다른 위치에도 연결된 파일(하드 링크)은 건너뜁니다.
• read_file은 기본적으로 한 번에 최대 1,000줄을 반환하며, 에이전트는 offset과 max_lines로 이어서 읽습니다. 일부만 반환된 페이지는 파일 내용이 아닌 안내 줄로 끝납니다.

MCP 도구¶

에이전트의 도구 목록에서 켠 MCP 도구는 채팅과 토론방, 실행에서 데스크톱과 헤드리스 서버 모두 실행됩니다. 단일 에이전트 실행과 같은 방식으로, 같은 도구 정책과 호출 빈도 제한, 경로 검사를 거쳐 실행되며, 모든 호출은 도구 감사 로그에 기록됩니다.

• 에이전트에게 도구를 켜는 것이 승인이므로, 호출마다 승인 요청이 표시되지 않습니다. 에이전트는 도구 목록에서 켜지 않은 MCP 도구를 실행할 수 없고, 다른 도구를 켜 둔 서버의 도구라도 마찬가지입니다.
• MCP 도구는 스쿼드 워크스페이스 안으로 제한되지 않습니다. 스쿼드의 명령 실행 설정과 관계없이 해당 서버가 접근할 수 있는 대상에 작업합니다.
• 도구는 해당 서버가 연결되어 있을 때만 에이전트에게 제공됩니다.
• 도구가 반환한 이미지는 이미지를 읽는 모델을 사용하는 에이전트에게 다음 모델 호출에서만 표시됩니다. 다른 모델에는 도구가 이미지를 반환했지만 해당 모델은 읽을 수 없다는 안내가 전달됩니다.

명령 실행¶

스쿼드 ⋯ 메뉴의 명령 실행은 스쿼드 에이전트가 명령과 Python 코드를 실행할지, 어디서 실행할지 정하는 설정입니다. 대상 도구는 run_command와 run_python, 그리고 이전 이름인 run_shell과 execute_python입니다. 설정은 실행, 에이전트 채팅, 토론방에 적용되며, 다음 실행이나 턴부터 반영됩니다.

작업 폴더에서 실행을 선택한 경우:

• 명령은 단일 에이전트 실행의 코드 실행과 같은 검사를 거치며, 코드 실행 샌드박스 폴더 대신 스쿼드 워크스페이스가 사용됩니다. 워크스페이스는 명령이 시작되는 위치이자 벗어날 수 없는 경계입니다. 워크스페이스 밖을 가리키는 경로 인자는 거부되고, run_python 코드는 워크스페이스 안의 파일만 열 수 있습니다.
• run_command는 호출 한 번에 명령 하나를 실행합니다. 파이프, 리디렉션, &&, ;는 거부되므로, 프로그램을 빌드하고 실행하려면 cc main.c -o main과 ./main처럼 호출을 두 번 합니다.
• 해당 선택은 스쿼드가 실행하는 모든 명령에 대한 승인이므로, 명령마다 승인 요청이 표시되지 않습니다. 모든 호출은 도구 감사 로그에 기록됩니다.
• 도구 목록에서 run_command나 run_python을 켠 에이전트만 명령을 실행합니다.
• 헤드리스 서버에서 run_python을 사용하려면 서버에 Python이 설치되어 있어야 합니다.

컨테이너에서 실행을 선택한 경우:

• run_command나 run_python 호출마다 명령 실행 이미지로 새 컨테이너가 시작되고, 명령이 끝나면 컨테이너가 제거됩니다. 스쿼드 워크스페이스만 /workspace에 읽기·쓰기로 연결되며, 해당 위치에서 명령이 시작됩니다. 명령이 작성한 파일은 이 컴퓨터의 워크스페이스에 그대로 남습니다.
• run_command는 bash에서 실행되므로 cc main.c -o main && ./main을 호출 한 번으로 실행할 수 있습니다. run_python은 코드를 입력으로 받아 python3로 실행됩니다.
• 컨테이너에서 네트워크 사용을 켜지 않으면 컨테이너에 네트워크가 없습니다. pip install 같은 명령에는 해당 설정을 켜세요. 설정이 꺼진 상태에서 다운로드가 실패하면 결과에 해당 이유가 표시됩니다. pip install --user로 설치한 패키지는 /workspace/.local에 남아 다음 명령에서도 사용됩니다.
• 컨테이너는 root가 아닌 현재 사용자로 실행되며, CPU 2개, 메모리 2 GiB, Docker에서는 프로세스 수 제한, 그리고 도구의 제한 시간이 적용됩니다. run_python 호출은 이 컴퓨터에서와 마찬가지로 설정 > 도구 및 확장 > Python 샌드박스의 실행 제한 시간이 지나면 멈춥니다. 같은 화면의 최대 메모리는 컨테이너에는 적용되지 않으며, 컨테이너의 2 GiB가 상한입니다.
• 명령 실행 이미지는 amd64와 arm64용으로 배포되는 python:3.14.8-bookworm이며 bash, Python 3, git, gcc, make가 포함되어 있습니다. squad.commandImageTag 설정으로 태그를 바꿀 수 있습니다. 대화상자에는 명령을 실행할 런타임과 이미지 유무가 표시되고, 이미지 받기로 이미지를 받을 수 있습니다.
• Docker와 Apple Container를 지원합니다. Apple Container는 네트워크 없이 컨테이너를 시작할 수 없으므로, 네트워크가 꺼진 경우 Docker가 있으면 Docker에서 실행됩니다.
• 런타임이나 이미지가 없으면 실행이 시작되지 않습니다. 실행 전 확인에서 무엇이 없는지 알려 주고 이미지 받기를 제공합니다. 명령이 이 컴퓨터에서 대신 실행되는 경우는 없습니다.

CLI에서는 aigo squad update <squad-id> --command-execution workspace(또는 off, container)와 --container-network on으로 설정합니다. aigo squad command-container status <squad-id>로 런타임과 이미지를 확인하고, aigo squad command-container pull <squad-id>로 이미지를 받습니다. 호출 한 번에 명령 여러 개가 필요한 작업은 폴더를 연결한 코워크 대화나 단일 에이전트 실행에서 진행하세요. 해당 명령은 파일과 명령이 실행되는 위치와 워크스페이스 모드의 규칙에 따라 실행됩니다.