Task Assets: 당신이 잠든 사이에도 실행되는 에이전트 워크플로우 (Agent Workflows)

이 글은 AI 코딩 에이전트가 의존하는 점점 늘어나는 기술, 스크립트, 그리고 컨텍스트(Context)를 관리하는 시리즈의 11번째 파트입니다. 9부에서는 워크플로우 에셋(Workflow assets)과 재개 가능한 절차(Resumable procedures)를 다루었습니다. 10부에서는 당신의 저장소(Stash)를 지속적으로 큐레이션하는 개선 파이프라인(Improve pipeline)을 소개했습니다. 이전 파트들에서는 팀, 분산 저장소(Distributed stashes), 그리고 커뮤니티 지식(Community knowledge)을 다루었습니다.

AI 에이전트를 활용한 대부분의 자동화는 반응적(Reactive)입니다. 세션을 열고, 에이전트에게 작업을 부여하고, 결과를 기다린 뒤, 세션을 닫습니다. 에이전트의 시계는 당신이 실행할 때만 돌아갑니다.

Task assets는 그 모델을 뒤집습니다. 작업(Task)은 당신의 저장소(Stash)에 있는 YAML 파일로, 워크플로우(Workflow) — 즉, 무엇을 실행할지, 언제 실행할지, 어떤 환경이 필요한지, 그리고 실행 허용 시간은 얼마인지 — 를 정의합니다. 일단 등록되면, 작업은 당신의 개입 없이 예정된 일정에 따라 실행됩니다. OS 스케줄러(OS scheduler)가 akm tasks run <id>를 호출하면, 작업이 실행되고 그 결과가 state.db에 기록됩니다. 당신은 akm health를 확인하거나 로그를 살펴볼 때 어떤 일이 일어났는지 알게 됩니다.

이것이 지속적인 운영을 가능하게 만드는 akm 0.8.0의 핵심 요소입니다. 개선 루프(Improve loop)는 Task asset이 그렇게 하라고 명시되어 있기 때문에 한 시간에 두 번 실행됩니다. 매시간 전송되는 Discord 상태 보고서(Discord health report)도 Task asset이 그렇게 하라고 명시되어 있기 때문에 발송됩니다. 둘 다 열려 있는 터미널(Terminal)을 필요로 하지 않습니다.

Task Asset 형식

Task asset은 <stash>/tasks/<id>.yml에 위치합니다. 파일 이름이 작업 ID(Task ID)가 됩니다. 최소한의 작업은 다음과 같습니다:

schedule: 0 * * * *
command: akm improve --auto-accept 90
enabled: true

이것만으로도 cron 항목을 설치하고 매 시간 정각에 akm improve를 실행하기에 충분합니다. 전체 스키마(Schema)에는 메타데이터(Metadata)와 작업별 타임아웃(Timeout) 제어가 추가됩니다:

schedule: "7,37 * * * *"
command: akm improve --auto-accept 90 --timeout-ms 1620000
enabled: true
...

가장 중요한 필드들은 다음과 같습니다:

필드 (Field)	필수 여부 (Required)	용도 (Purpose)
`schedule`	예	표준 cron 표현식. Linux의 crontab, macOS의 launchd plist, Windows의 schtasks XML에 매핑됩니다. 특수 문자가 포함된 표현식은 따옴표로 감싸야 합니다.
...

command: vs prompt:

command와 prompt의 구분은 두 가지 서로 다른 실행 모델을 반영합니다.

command 태스크는 셸 호출 (shell invocation)입니다. akm tasks run은 해당 문자열을 자식 프로세스 (child process)에서 직접 실행합니다. 여기에는 에이전트 (agent)가 관여하지 않습니다. 명령은 akm을 호출하거나, 셸 스크립트 (shell script)를 실행하거나, 임의의 바이너리 (binary)를 호출할 수 있습니다. 종료 코드 (exit code)가 로그에 기록됩니다.

command: akm improve --auto-accept 90

prompt 태스크는 기본 에이전트 프로필(default agent profile) 또는 --profile로 지정된 프로필에 설정된 에이전트에게 작업을 전달합니다. prompt의 값은 태스크 지침 (task instruction)이 됩니다. 에이전트는 자율적으로 실행되며, 허용된 도구 세트 (tool set)에 따라 akm 명령을 사용하고, 파일을 작성하며, 도구를 호출할 수 있습니다. 결과는 에이전트가 정상적으로 종료되는지 여부에 따라 결정됩니다.

prompt: |
  Run akm wiki ingest research and then run akm wiki lint research.
  Fix any orphan pages the lint step reports.

실무적인 구분: 실행 과정이 완전히 스크립트로 작성되어 있고 결과가 결정론적 (deterministic)인 태스크에는 command를 사용하십시오. 에이전트가 판단력을 발휘하여 콘텐츠를 합성하거나, 출력을 분류(triaging)하거나, 발견한 내용을 바탕으로 의사결정을 내리기를 원할 때는 prompt를 사용하십시오. curate-to-wiki 태스크는 후자의 좋은 예시입니다. 이 태스크는 에이전트가 각 단계의 지침을 읽고, 매개변수 (parameters)를 치환하며, 워크플로우 실행을 완료할 때까지 진행하는 다단계 워크플로우 (multi-step workflow)를 실행합니다. 워크플로우 자산 (Workflow assets) 자체는 이 시리즈의 9부에서 다룹니다.

태스크 등록하기 (Registering Tasks)

스케줄러 (scheduler)에 태스크를 넣는 방법에는 두 가지가 있습니다.

첫 번째 방법은 akm tasks add로, YAML 파일을 생성하고 한 번에 설치하는 방식입니다:

akm tasks add my-task \
  --schedule "0 9 * * *" \
  --command "akm improve --auto-accept 80" \
...

두 번째 방법은 YAML 파일을 stash의 tasks/ 디렉토리에 직접 작성한 다음 다음 명령어를 호출하는 것입니다:

akm tasks sync

sync는 tasks/ 내의 모든 .yml 파일을 OS 스케줄러(OS scheduler)와 대조하여 조정(reconcile)합니다. enabled: true 상태이지만 아직 설치되지 않은 모든 태스크는 스케줄러 항목에 등록됩니다. enabled: false이거나 누락된 태스크는 해당 항목이 제거됩니다. 이는 새 태스크 파일이나 업데이트된 태스크 파일이 포함된 stash 변경 사항을 pull한 후에 실행해야 하는 올바른 명령어입니다.

기타 태스크 관리 명령어:

akm tasks list                        # 상태를 포함한 정의된 모든 태스크
akm tasks show <id>                   # 파싱된 YAML + 스케줄러 상태
akm tasks run <id>                    # 즉시 실행
...

akm tasks run은 스케줄러가 호출하는 것과 동일한 명령어입니다. 스케줄에 등록하기 전에 태스크를 즉시 실행하여 테스트할 수 있습니다.

akm env run을 이용한 환경 주입 (Environment Injection)

비밀 정보(secrets)나 환경별 설정(environment-specific configuration)이 필요한 태스크는 akm env 볼트(vaults)를 사용합니다. 볼트는 stash의 env/<name>.env 경로에 저장되는 암호화된 .env 파일입니다. akm env run을 사용하여 이를 자식 프로세스(child process)에 주입합니다:

akm env run env:fwdslsh -- bash ./scripts/post-to-discord.sh

env: 접두사는 표준 참조 형식(canonical ref form)입니다. 태스크 YAML에서 akm은 이름만 있는 볼트 명칭(bare vault names)도 해석합니다. 아래의 실습 예제에서는 실제 운영 파일과 정확히 일치시키기 위해 이름만 사용했습니다.

태스크의 command 필드에서도 동일한 패턴이 직접 적용됩니다:

command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh

이렇게 하면 fwdslsh 볼트에 있는 모든 변수가 스크립트를 실행하는 셸 프로세스(shell process)에 주입됩니다. 변수들은 해당 자식 프로세스 내에서만 존재하며, 디스크에 기록되거나 부모 환경(parent environment)으로 내보내지지(export) 않습니다. 태스크 정의 자체에는 비밀 정보가 포함되지 않고 오직 볼트 참조(vault reference)만 포함됩니다. 따라서 자격 증명(credentials)을 노출하지 않고도 태스크 YAML을 stash에 커밋하고 공유할 수 있습니다.

만약 태스크가 Vault의 변수 중 일부만 필요하다면, --only를 사용하여 주입(injection) 범위를 좁힐 수 있습니다:

akm env run env:fwdslsh --only DISCORD_WEBHOOK_URL -- bash ./post.sh

--only는 단일 키 또는 쉼표로 구분된 목록을 허용합니다. 특정 키를 제외한 Vault의 모든 항목을 주입하려면 --except를 사용하세요.

실습 예제: Discord 상태 보고서 (The Discord Health Report)

이것은 개선 파이프라인(improve pipeline)을 모니터링하기 위해 운영 환경에서 사용되는 상태 보고서 태스크입니다:

# ~/akm/tasks/akm-health-report.yml
schedule: 0 * * * *
command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh
...

이 태스크는 매 시간 정각에 실행됩니다. fwdslsh Vault(Discord 웹훅 URL 및 스크립트에 필요한 기타 자격 증명 포함)를 주입한 다음, 상태 보고서 스크립트를 실행합니다. 스크립트는 akm health --since=4h와 akm health --since=8h를 호출하여, 트렌드 문맥(trend context) 파악을 위해 두 시간대 사이의 차이(deltas)를 계산하고, 포맷팅된 임베드(embed)를 Discord에 게시합니다.

임베드에는 세 가지 인라인 필드 — 출력(Output: 프로모션된 참조(promoted refs), 병합된 메모리(merged memories), 메모리 추론 수율(memory inference yield)), 실패(Failures: 청크 실패(chunk failures), 스킵 사유 이상(skip reason anomalies)), 지연 시간(Latency: 중앙값(median), P95, 이전 시간대 비교) — 와 더불어, 실제로 문제가 발생했을 때만 나타나는 '주의 필요(Needs Attention)' 섹션이 포함되어 있습니다. 푸터(footer)에는 호스트 이름과 실행 타임스탬프가 포함되어 있어, 여러 머신에서 생성된 보고서를 한눈에 구분할 수 있습니다.

YAML을 작성한 후 태스크를 등록하려면:

akm tasks sync
akm tasks list
# → akm-health-report   0 * * * *   enabled   last run: —

예약된 버전에 의존하기 전에 스크립트가 제대로 작동하는지 확인하기 위해 즉시 한 번 실행해 보세요:

akm tasks run akm-health-report

결과를 확인합니다:

akm tasks history --id akm-health-report --limit 5

로깅 (Logging)

모든 태스크 실행은 state.db 내의 task_history 테이블에 기록됩니다. akm tasks history 명령어가 해당 데이터를 보여줍니다. 로그 출력의 경우, 각 실행은 다음 경로에 기록됩니다:

~/.cache/akm/tasks/logs/<id>.log

akm health는 누락된 로그 파일, 오래된 활성 실행(시작되었으나 완료되지 않은 작업), 그리고 최근 실패율을 확인하기 위해 task_history를 검사합니다. tasks_completed 이벤트를 기록하지 않은 작업 실행은 akm health 출력 결과에 '멈춰 있는 활성 실행(stuck active run)'으로 나타납니다. 이는 로그 파일에 구체적인 내용이 없더라도 무언가 잘못되었다는 것을 알려주는 신뢰할 수 있는 신호입니다.

akm health --since 4h

상태 검사(health check)는 task_history 이벤트와 디스크의 로그 파일을 상관 분석합니다. 완료된 실행에 대한 로그 파일이 누락된 경우, logBackingRate가 1.0 미만으로 떨어지며 이는 경고(warning)로 표시됩니다. 이것이 바로 task-log-backing 하드 체크(hard check)로, akm health가 어떠한 메트릭(metrics)을 살펴보기 전에 실행하는 결정론적 검사(deterministic checks) 중 하나입니다.

작업 중심 운영 구축하기 (Building a Task-Driven Operation)

여러 작업이 함께 작동하면서 나타나는 패턴은 스스로 실행되는 운영 체계입니다. 개선 루프(improve loop)는 한 시간에 두 번 스태시(stash)를 통합하고 큐레이션합니다. 해당 파이프라인이 내부적으로 수행하는 작업은 10부에서 다룹니다. 상태 보고서(health report)는 매시간 결과를 표면화합니다. 일일 큐레이션 작업은 설정된 소스에서 새로운 기사를 가져와 연구 위키(research wiki)로 수집합니다. 이 중 그 어떤 것도 열려 있는 터미널을 필요로 하지 않습니다.

새로운 자동화된 동작을 추가하는 과정은 작업의 내용과 관계없이 동일한 단계를 따릅니다:

<stash>/tasks/<id>.yml에 YAML 파일을 작성합니다.
akm tasks sync를 실행하여 스케줄러 항목을 설치합니다.
akm tasks run <id>를 실행하여 즉시 테스트합니다.
akm tasks history로 출력을 확인하고 로그를 점검합니다.
스태시와 함께 버전 관리(version-controlled)를 하고 싶다면 작업 파일을 git에 추가합니다.

작업 YAML은 당신이 원하는 일과 그 일이 일어나는 시점 사이의 계약(contract)입니다. 로그와 state.db는 실제로 일어난 일에 대한 기록입니다.

Task assets는 akm 0.8.0에서 사용할 수 있습니다. 전체 명령어 참조(command reference)는 docs/cli.md에서 확인할 수 있습니다. 환경 볼트(environment vault) 문서는 docs/cli.md에 있습니다. 만약 0.7.x 버전에서 업그레이드하는 경우, 이전 형식의 task .md 파일은 자동으로 검색되지 않습니다 — 변환 경로에 대해서는 마이그레이션 가이드(migration guide)를 확인하세요.