---
title: "Todo와 clarify"
description: "Ankole 에이전트가 복잡한 작업을 계획하고 작업 중에 실제 모호함을 해결하는 방식 — todo 도구(세션별, 진행 중 항목 최대 1개)와 clarify 도구(결정 질문 1개, 영구 기록, 턴 종료). 에이전트가 각각을 언제 사용하는지, 운영자가 이들에서 기대해서는 안 되는 것."
url: "https://ankole.agentbull.com/ko-KR/docs/todo-and-clarify/"
lang: "ko-KR"
---

> AI Agent용 문서 색인: https://ankole.agentbull.com/ko-KR/llms.txt

# Todo와 clarify

`todo`와 `clarify`는 에이전트의 구조화된 계획 도구입니다. 하나는 세션 안에서 계획을 유지하고, 다른 하나는 답이 실제로 결과를 바꿀 때 단 하나의 질문을 합니다. 둘 다 `app/agent_computer/src/tools/`에서 worker와 함께 제공됩니다. 이들은 memory도 아니고 채팅 표면도 아닙니다 — 에이전트가 자신의 발판을 유지하는 방법이자 하나의 결정을 요청하는 방법입니다.

먼저 핵심 속성을 밝힙니다: todo 목록은 일시적이고 세션별이며, `clarify` 호출은 턴을 종료합니다. 목록은 세션을 넘어 생존하지 않고, 에이전트가 질문하면 다음 메시지로 사용자의 답변을 기다립니다. 어느 도구도 영구적인 진실이 아닙니다 — 그 역할은 Memory에 있습니다.

## 각 도구의 정체

- **`todo`** (`tools/todo/todo-tool.ts`, 182행) — 현재 세션의 작업 목록을 관리합니다. 3단계 이상의 복잡한 작업이나 사용자가 여러 작업을 제시했을 때 사용하세요. 목록 순서가 우선순위입니다. 한 번에 `in_progress` 항목은 하나뿐입니다. 완료되는 즉시 항목을 완료로 표시하고, 실패한 항목은 취소하고 수정된 항목을 추가하세요.
- **`clarify`** (`tools/clarify/clarify-tool.ts`) — 답이 의도한 결과나 다음 행동을 선택하는 데 필요할 때만 사용자에게 질문 하나를 합니다. 에이전트는 먼저 요청과 이전 대화를 사용하며, 이미 제시한 선호에 대해 묻지 않고 안전하고 위험이 낮은 기본값이 있을 때도 묻지 않습니다. 성공하면 정규화된 질문과 선택지를 영구적으로 기록하고 현재 턴을 종료합니다.

todo 목록은 세션 범위의 `TodoStore`에 존재합니다. 이것은 기록이 아니라 작업 상태입니다. 허용되는 상태는 네 가지입니다: `pending`, `in_progress`, `completed`, `cancelled`.

## 에이전트가 todo를 사용하는 시점

작업의 단계가 많아 컨텍스트에만 두는 것이 부담이 될 때 에이전트는 `todo`를 사용합니다. 3단계 이상이거나 여러 작업이 한 번에 주어진 경우가 트리거입니다. 목록이 만들어지면 에이전트는 세 가지 규칙을 따릅니다:

1. **목록 순서가 우선순위입니다.** 첫 번째 항목이 에이전트가 다음에 할 항목입니다.
2. **진행 중 항목은 최대 하나입니다.** 에이전트는 첫 번째 단계를 끝내거나 취소하기 전에 두 번째 단계를 시작하지 않습니다.
3. **항목은 즉시 완료로 표시합니다.** 완료된 단계는 현재 항목이 아니라 `completed`로 목록을 떠납니다. 실패한 단계는 `cancelled`가 되고 수정된 항목이 추가됩니다.

todo 목록이 아닌 것: 그것은 영구 계획이 아니며, 다음 세션에 작업을 넘기는 방법도 아닙니다. 새 세션은 빈 목록으로 시작합니다. 계획이 세션보다 오래 살아남아야 한다면 `todo`가 아니라 Memory에 들어갑니다.

## 에이전트가 clarify를 사용하는 시점

`clarify`는 의도한 결과나 다음 행동을 선택하는 데 답이 필요한 단 하나의 질문을 위한 것입니다. 계약은 의도적으로 좁습니다. 에이전트는 자족적인 질문 하나를 하고 개방형 답변을 받거나 실질적으로 다른 두 가지에서 네 가지 선택지를 제시합니다. 각 선택지는 그 결과 또는 트레이드오프를 명시하며, 거절할 수 있는 행동에는 무행동 선택지가 포함됩니다. 그러면 에이전트는 멈춥니다. 성공적인 호출에서는 세 가지가 일어납니다:

- 정규화된 질문과 선택지가 영구적으로 기록되어 나중에 결정을 추적할 수 있습니다;
- 현재 턴이 종료됩니다 — 에이전트는 더 이상 답변을 내지 않고 추가 도구도 호출하지 않습니다;
- 사용자의 답변이 다음 사용자 메시지로 도착하고, 에이전트는 거기서 작업을 다시 이어갑니다.

즉, `clarify` 호출은 긴 턴 속의 일시정지가 아니라 깔끔한 인계입니다. 사용자는 편한 시간에 답하면 되고, 이어지는 턴은 사용자의 답변으로 시작하는 새 턴입니다.

질문하기 전에 에이전트는 사용자의 요청과 이전 대화를 사용합니다. 이미 제시한 선호를 반복하지 않고, 안전하고 위험이 낮은 기본값이 있으면 방해하지 않습니다. 작업 후 피드백은 사용자의 답변이 작업의 수용, 수정, 계속 여부를 결정할 때만 요청합니다.

## clarify가 백그라운드 Job에 연결되는 방식

[백그라운드 Job](https://ankole.agentbull.com/ko-KR/docs/background-jobs/index.md) 안에서 `clarify` 호출은 Job을 `waiting_on_user` 상태로 이동시킵니다. Job은 사용자가 답할 때까지 더 실행되지 않으며, 사용자의 답변이 다시 running 상태로 되돌립니다. 사용자의 관점에서는 Job이 정확히 한 가지 질문을 하려고 일시정지한 것처럼 보입니다. 에이전트의 관점에서는 동일한 계약, 즉 질문하고, 턴을 끝내고, 다음 메시지를 기다리는 것이 Job 수명 주기 안에 적용된 것입니다. 상태 모델과 사용자를 기다리는 Job을 알아보는 방법은 [Background Agent Jobs](https://ankole.agentbull.com/ko-KR/docs/background-jobs/index.md)를 참조하세요.

## 운영자가 건드리지 않는 것

todo 저장소, clarify 영구 기록, 턴 종료 동작은 Console에서 조정할 수 있는 설정이 아니라 worker 내부입니다. 에이전트가 질문해야 할 때 질문하지 않거나 너무 자주 질문한다면, 해결책은 worker 플래그가 아니라 에이전트의 페르소나와 능력 집합에 있습니다 — [Agents](https://ankole.agentbull.com/ko-KR/docs/agents/index.md) 참조. 기록된 결정은 이를 쓴 동일한 worker 표면을 통해 감사할 수 있으며, 운영자가 손으로 편집하지 않습니다.

## 다음 단계

- 에이전트가 언제 계획하고 언제 질문하는지를 형성하는 페르소나와 능력에 대해서는 [Agents](https://ankole.agentbull.com/ko-KR/docs/agents/index.md)를 읽으세요.
- 세션을 넘어 생존하는 영구 지식은 Memory에 속합니다.
- `waiting_on_user` Job 상태와 Job 안의 clarify가 Job을 일시정지시키는 방법에 대해서는 [Background Agent Jobs](https://ankole.agentbull.com/ko-KR/docs/background-jobs/index.md)를 읽으세요.
- 턴 중에 이러한 도구를 실행하는 worker에 대해서는 [Agent Computer Worker](https://ankole.agentbull.com/ko-KR/docs/agent-computer-worker/index.md) 개발자 페이지를 읽으세요.