본문으로 건너뛰기
Ankole

Todo와 clarify

AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/todo-and-clarify/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

todo와 clarify는 Ankole.Sessions.Tools.Session 모듈이 소유하는 제어 플레인 도구입니다. Driver가 호출 인수를 검증한 뒤 AIGateway를 통해 모델 가시 결과를 기록하고, 그 변경을 현재 실행 상태에 반영합니다.

작업 목록

todo 도구는 현재 작업 목록을 조회하거나 전체 교체하고, 항목 ID 기준으로 변경 사항을 병합합니다. 각 항목은 pending, in_progress, completed, cancelled 중 하나의 상태를 가지며 최대 256개 항목까지 등록할 수 있습니다. 시스템 지침에서는 세 단계 이상으로 이루어진 복합 작업을 수행할 때 목록을 우선순위 순으로 구성하고, 동시에 in_progress인 항목은 하나만 유지하며, 단계가 끝나는 즉시 완료 표시를 남기고 실패 시 수정 항목을 추가하도록 안내합니다.

이 목록은 Ankole.Sessions.Run 내부의 실행 중 작업 상태입니다. 프로세스 복구 시에는 현재 실행 이력에 기록된 성공 도구 호출들을 바탕으로 목록을 다시 재구성하며, 새 Session을 시작할 때 다른 Session의 목록을 물려받지는 않습니다. 여러 Session 사이에 공유해야 하는 지식은 Brain에 기록합니다.

결정 질문 하나

clarify 도구는 사용자의 답변에 따라 최종 결과나 다음 행동이 달라질 때만, 그 자체로 맥락이 완결된 질문 하나를 던지는 데 사용합니다. Agent는 먼저 현재 요청과 앞선 대화 기록을 살펴보며, 이미 밝혀진 선호 사항을 되묻지 않고 안전하고 위험 부담이 낮은 기본값이 있다면 작업을 멈추지 않고 그대로 진행합니다.

질문에는 자유 텍스트 응답을 받을 수도 있고, 서로 겹치지 않는 2~4개의 선택지를 제시할 수도 있습니다. 길이 한도는 질문 본문 2,000자, 선택지 라벨 200자, 선택지 설명 500자이며, 사용자가 실행을 원치 않을 수 있는 작업에는 취소·보류에 해당하는 선택지를 함께 넣어야 합니다.

호출이 성공하면 정규화된 질문과 선택지를 기록하고 즉시 현재 턴을 종료하며, 같은 턴에서 추가 도구를 호출하거나 별도 최종 답변을 덧붙이지 않습니다. 네이티브 Pod Chat에서는 제어 플레인이 질문 스냅샷을 rich_content["clarify"]에 저장해 대화형 **ChoiceCard**로 렌더링하고, Delivery 상호작용 체크포인트가 pending -> answered | superseded 상태 전이를 관리합니다(같은 Agent가 새 질문을 보내면 미해결 상태였던 이전 질문은 superseded로 전환됩니다). 대화방 구성원은 ChoiceCard에서 선택지를 고르거나 직접 텍스트를 입력해 응답할 수 있으며(선착순 잠금이 적용되어 동시에 들어온 중복 응답은 HTTP 409를 반환), Pod Chat이나 외부 메신저 채널에서 일반 채팅 메시지로 답장해 다음 턴을 이어갈 수도 있습니다. 질문과 채택된 답변은 모두 영구 대화 기록에 남습니다.

구조화된 양식

답변에 형식이 정해진 값이 여러 개 필요하면 Agent는 choices 대신 fields를 전달합니다. 양식 하나에는 필드를 15개 담을 수 있습니다. 각 필드에는 snake_case 형식의 id, 최대 80자의 label, 최대 200자의 선택적 안내 문구 help, 기본값이 true인 required, 선택적 기본 입력값 default가 있으며, 유형은 다음 중 하나입니다. text(한 줄 또는 multiline, max_length는 최대 1,000, 기본값 200), number(integer, min, max, 단위 레이블 unit), date(YYYY-MM-DD, 선택적 min과 max), select 또는 multi_select(value와 label을 가진 옵션 210개, multi_select는 min_items와 max_items도 지정 가능), boolean. 양식에는 필수 필드가 하나 이상 있어야 합니다. 필드 ID나 옵션 값이 중복되거나, 최솟값이 최댓값보다 크거나, 기본값이 유효하지 않거나, 필수 필드가 하나도 없으면 컨트롤 플레인이 정의를 거부하고, Agent가 호출을 고칠 수 있도록 그 이유를 돌려줍니다.

Pod Chat에서는 ChoiceCard가 양식을 유형에 맞는 입력 컨트롤로 표시합니다. 컨트롤 플레인은 제출될 때마다 다시 검증합니다. 잘못된 제출이면 해당 필드 아래에 오류가 표시되고 질문은 답변 대기 상태로 남으며, 처음으로 유효하게 제출된 답이 채택됩니다. 대화방에는 필드 레이블로 구성한 한 줄 요약이 표시되고, Agent는 이 요약과 함께 JSON 형식의 값을 받습니다. 선택형 필드에는 옵션의 value가 담깁니다. 자신의 말로 답하고 싶은 구성원은 여전히 작성기에서 질문을 열어 답할 수 있습니다.

Feishu/Lark와 Microsoft Teams는 답장 카드에 양식을 바로 표시하고, 같은 양식을 Pod에서 여는 버튼도 함께 보여 줍니다. 컨트롤 플레인은 카드에서 제출할 때마다 값을 검증합니다. 유효하지 않은 제출은 질문을 열어 둔 채 고쳐야 할 필드를 알려 주며, Feishu/Lark에서는 토스트로, Teams에서는 답장으로 표시됩니다. 첫 번째 유효한 제출이 답변으로 확정되고, Feishu/Lark와 Teams에서는 양식이 답변 요약으로 바뀝니다. 그 밖의 외부 채팅 채널에는 질문, 필드 레이블, Pod 링크(/?interaction=<id>)가 전달됩니다. 링크를 열면 대화 상자에 양식이 표시되지만 여는 것만으로는 답변이 되지 않습니다. 누군가 카드나 Pod에서 유효한 양식을 제출하거나 채널에서 답장할 때까지 질문은 답변 대기 상태로 남습니다.

Background Job과 운영

Native Codex 기반의 Background Job은 별도의 사용자 입력 요청 경로를 사용합니다. 작업 도중 사람의 확인을 요청하면 Job 상태가 waiting_on_user로 바뀌면서 점유하던 실행 슬롯을 반납하고, 소유자가 답변을 보내면 그 시점에 실행을 재개합니다. 자세한 수명 주기 계약은 Background Agent Jobs를 참조하세요.

계획 목록 관리와 질문 후 턴 종료 동작을 켜고 끄는 별도의 Console 플래그는 없습니다. Agent가 계획을 세우거나 되묻는 기준을 조정하려면 Agent의 지침 문서와 활성화된 기능을 수정하세요. 관련 내용은 Agents와 Agent loop를 참조하세요.