Managed Deep Agents에 스케줄 추가하기

Managed Deep Agents에 스케줄 추가하기

Managed Deep Agents 배포에 관리형 cron 스케줄을 선언하는 방법을 알려드릴게요.

Managed Deep Agents는 cron 스케줄에 따라 에이전트를 실행할 수 있어요. 프로젝트를 배포하면 mda deploy가 각 스케줄을 배포가 완료된 뒤 LangSmith cron으로 프로비저닝합니다.

참고: Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 리전에서만 사용할 수 있어요.

출처: 문서

본문

프로젝트 구조

스케줄 선언은 프로젝트 수준의 schedules/ 디렉터리에 있으며, 파일 하나당 스케줄 하나를 담습니다:

my-agent/
  agent.ts
  schedules/
    daily-digest.ts

스케줄 추가하기

파일 이름이 관리형 스케줄 이름이 됩니다.

스케줄 모듈은 이름이 지정된 schedule 선언을 내보내야 합니다.

import { defineSchedule } from "managed-deepagents";

export const schedule = defineSchedule({
  cron: "0 8 * * 1-5",
  timezone: "America/Los_Angeles",
  prompt: "Write the daily digest.",
});

스케줄 입력 구성하기

각 스케줄은 다음 중 정확히 하나를 정의해야 합니다:

  • prompt: 자연어 프롬프트. Managed Deep Agents는 cron이 발화할 때 이를 사용자 메시지로 변환합니다.
  • input: 구조화된 LangGraph 입력 객체. 단일 프롬프트 대신 커스텀 그래프 입력을 전달해야 할 때 사용합니다.
import { defineSchedule } from "managed-deepagents";

export const schedule = defineSchedule({
  cron: "30 2 * * *",
  input: {
    messages: [
      { role: "user", content: "Sweep stale tickets and summarize changes." },
    ],
  },
});

cron은 표준 5개 필드 cron 표현식(분, 시, 일, 월, 요일)이어야 합니다. timezone을 생략하면 LangSmith crons는 UTC를 사용합니다.

스레드 동작 선택하기

스케줄은 기본적으로 임시(ephemeral) 스레드를 사용합니다. Managed Deep Agents는 각 실행마다 새 스레드를 만들고, 실행이 끝나면 해당 임시 스레드를 LangSmith에 삭제하도록 요청합니다.

스케줄 실행이 호출 간 영구 스레드 상태를 누적해야 하는 경우에만 영구 스레드를 사용하세요.

참고: 다음 예제는 영구 메모리가 필요합니다.

import { defineSchedule } from "managed-deepagents";

export const schedule = defineSchedule({
  cron: "0 3 * * *",
  prompt: "Review the current project memory and list follow-up tasks.",
  thread: { mode: "persistent", id: "nightly-memory" },
});

결과를 Slack으로 전달하기

deliverTo를 설정하면 최종 응답을 구성된 Slack 채널로 게시합니다.

스케줄 실행은 발신 스레드가 없으므로 Slack 채널 ID를 사용합니다.

참고: 스케줄 전달에는 managed-deepagents 0.4.0 이상 버전이 필요합니다.

import { defineSchedule } from "managed-deepagents";

export const schedule = defineSchedule({
  cron: "0 9 * * 1",
  prompt: "Write a short Monday greeting.",
  deliverTo: {
    channel: "slack",
    to: {
      type: "provider_conversation",
      conversationId: "C0123456789",
    },
  },
});

Slack 봇은 대상에 접근할 수 있어야 합니다.

정적 선언 사용하기

스케줄 선언은 컴파일 시점에 추출됩니다. 스케줄 구성을 정적으로 직렬화할 수 있게 유지하세요:

  • 리터럴, 배열, 객체, 최상위 리터럴 상수에 대한 참조를 사용하세요.
  • 환경 변수를 읽거나, 함수를 호출하거나, 객체를 펼치거나, 스케줄 값을 동적으로 계산하지 마세요.
  • 동적 동작은 에이전트, 도구, 미들웨어, 런타임 컨텍스트에 두세요.

스케줄 배포하기

mda dev로 프로젝트를 로컬에서 테스트한 뒤 mda deploy로 배포합니다. LangSmith에서 배포 추적을 열어 모델 호출, 도구 호출, 오류, 지연 시간을 검사하세요.

배포가 DEPLOYED 상태가 되면 mda deploy는 배포된 Agent Server에서 Managed Deep Agents 소유의 기존 cron 작업을 찾아 삭제하고, 현재 schedules/ 선언에 대한 cron 작업을 만듭니다. 로컬 스케줄 파일을 제거하고 다시 배포하면 해당 관리형 cron도 제거됩니다.

경고: --no-wait로 배포하면 CLI가 원격 빌드를 트리거하고 배포가 DEPLOYED에 도달하기 전에 종료되므로, 해당 호출에서는 스케줄을 조정하지 않습니다. 스케줄을 추가·변경·제거할 때는 --no-wait 없이 mda deploy를 실행하세요.

스케줄 문제 해결

  • must export a named schedule declaration: schedules/의 각 파일에서 최상위 schedule을 내보내세요.
  • must define exactly one of prompt or input: prompt 또는 input 중 하나만 추가하되, 둘 다는 안 됩니다.
  • cron must be a standard 5-field expression: 초 기반 cron 문법이 아닌 5개 cron 필드를 사용하세요.
  • schedule is not static: 계산된 값을 리터럴 또는 최상위 리터럴 상수로 바꾸세요.
  • failed to create cron for schedule: LangSmith에서 배포 URL을 열어 배포된 Agent Server가 정상인지 확인하세요.

더 알아보기