For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

추천

Agents API

Agents SDK

ChatKit

API 대시보드
ChatGPT 사용해 보기

일정 기반 자동화

일정에 따라 에이전트 작업을 실행하거나 에이전트가 다음 작업을 직접 예약하도록 설정하세요.

일정 기반 자동화를 사용하면 cron 일정에 따라 에이전트 세션을 실행할 수 있습니다. 에이전트의 automations 도구를 활성화하면 에이전트가 작업을 수행하면서 다음 작업을 직접 예약할 수도 있습니다.

  • cron 일정으로 세션 자동화하기

    cron 표현식과 시간대를 지정해 새 세션을 시작하거나 기존 세션을 이어가세요.

  • 에이전트가 자동화를 만들도록 설정하기

    automations 도구를 추가하면 에이전트가 현재 세션에서 후속 작업을 예약할 수 있습니다.

  • 자동화 호출 모니터링하기

    각 호출에는 세션에 작업을 보내려는 시도가 기록됩니다. 호출 상태와 세션 ID를 확인하세요.
cron 일정으로 세션 자동화하기
import OpenAI from "openai";

const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
  type: "periodic",
  name: "Daily session",
  expression: "0 10 * * *",
  timezone: "America/New_York",
  target: {
    type: "new_session",
    agent_id: "agt_123",
    environment: { type: "openai_hosted" },
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Summarize the current status and next steps.",
          },
        ],
      },
    ],
  },
});
console.log(automation);

API 리소스

  • 에이전트

    /v1/agents

    작업에 필요한 지침과 도구를 정의합니다.

  • 자동화

    /v1/agents/automations

    실행 시점과 사용할 세션을 저장합니다.

  • 호출

    /v1/agents/automations/{automation_id}/invocations

    작업을 언제 보냈고 어느 세션이 받았는지 확인합니다.

  • 세션

    /v1/agents/sessions

    대화 기록과 도구를 활용해 작업을 실행합니다.

  • 세션 이벤트

    /v1/agents/sessions/{session_id}/events

    진행 상황을 추적하고 결과를 수집합니다.

활용 사례

작동 방식

자동화는 에이전트 작업을 위해 저장해 둔 일정입니다. Agents API는 일정을 저장하고 각 작업을 대상 세션으로 보냅니다.

  1. 작업을 정의하세요. 실행 시점을 정하고, 실행할 때마다 새 세션을 시작할지 기존 세션을 이어갈지 선택하세요.
  2. 작업을 보내세요. 실행할 때마다 호출 기록이 생성됩니다. 이 기록에는 대상 세션으로 작업을 보내려는 시도가 남습니다. 세션이 다른 작업을 처리 중이면 새 작업은 대기합니다.
  3. 결과를 추적하세요. 에이전트는 세션의 도구와 컨텍스트를 사용해 작업합니다. 세션 이벤트를 통해 진행 상황을 추적하고 결과를 수집하세요. 세션이 작업을 받았다고 해서 에이전트가 작업을 마쳤다는 뜻은 아닙니다.

애플리케이션은 API를 통해 일정을 만들거나 수정하거나 일시 중지하거나 삭제할 수 있습니다. automations 도구를 활성화하면 에이전트도 현재 세션에서 다음 확인 작업을 직접 예약할 수 있습니다.

세션과 일정 선택하기

작업에 이전 대화 기록이 필요한지에 따라 대상을 선택하세요.

대상 용도 필수 설정
new_session 월별 지출 검토처럼 독립적으로 수행하는 작업 에이전트, 환경, target.input에 지정한 초기 메시지
existing_session 해당 세션에서 이전에 확인한 내용이 필요한 후속 작업 세션 ID, target.instructions에 지정한 알림 문구

실행 시점은 대상과 별도로 선택하세요.

유형 실행 시점 필드 예시
periodic expression과 timezone 매일 오전 10시(America/New_York 기준)
once run_at 초 단위 Unix 타임스탬프로 지정한 미래 시점에 한 번 확인

두 일정 유형 모두 어느 대상에나 사용할 수 있습니다. 자동화를 만들면 상태가 active로 저장되며 작업이 즉시 실행되지는 않습니다. 주기적 자동화의 첫 실행 시점은 생성 이후 일정과 처음 일치하는 시각입니다.

매일 할 일 제안 예약하기

자동화를 만들기 전에 작업에 필요한 지침과 도구를 갖춘 에이전트를 만들고 사용자의 캘린더, 작업, 메시지에 접근할 수 있게 하세요. 여러 세션에서 에이전트 재사용하기를 참고하세요.

SDK에는 OpenAI-Beta: agents=v1 헤더가 포함되어 있습니다. cURL로 API를 호출할 때는 이 헤더를 직접 포함하세요.

다음 예시는 뉴욕 시간으로 매일 오전 10시에 새 세션을 시작하는 자동화를 만듭니다.

매일 할 일 제안 예약하기
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Daily suggestions",
    expression="0 10 * * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my calendar, tasks, and recent messages for today. "
                            "Suggest the most useful actions I could take today, "
                            "with a short reason for each."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

나중에 일정을 조회하거나 관리할 수 있도록 응답으로 받은 자동화 id를 저장하세요. 호출할 때마다 새 대화가 시작됩니다. 위 환경 설정은 해당 세션에 사용할 OpenAI 호스팅 샌드박스를 프로비저닝합니다.

에이전트 설정을 target.agent에 직접 지정하거나 저장된 에이전트의 ID를 target.agent_id에 지정할 수 있습니다. 두 필드 중 정확히 하나만 지정하세요. 초기 메시지는 target.input 안에 넣으세요. 요청의 최상위 수준에 넣으면 안 됩니다. 비어 있지 않은 텍스트나 이미지 URL을 담은 메시지를 하나 이상 포함하세요.

매월 지출 검토하기

월별 지출 검토에도 같은 방식을 사용할 수 있습니다. 저장된 에이전트에 사용자의 금융 기록을 조회할 권한을 부여한 다음, 매월 1일 오전 9시에 새 세션을 시작하도록 예약하세요.

월별 지출 검토 예약하기
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Monthly spending review",
    expression="0 9 1 * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my spending for the previous month. Flag unused "
                            "subscriptions, price increases, and other potential "
                            "savings for me to review."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

반복 실행 시점 설정하기

필드가 다섯 개인 cron 표현식과 시간대 이름을 함께 지정하세요.

표현식 일정
0 10 * * * 매일 오전 10시
0 */2 * * * 두 시간마다
0 9 1 * * 매월 1일 오전 9시
0 9 * * MON-FRI 월요일부터 금요일까지 오전 9시

시간대에 따라 표현식을 해석하는 기준이 달라집니다. UTC 기준 일정에는 UTC를, 현지 시간 기준 일정에는 America/New_York와 같은 IANA 시간대를 사용하세요. 주기적 자동화에는 run_at을 포함하지 마세요.

cron 일정은 선택한 시간대의 시각을 따릅니다. 예를 들어 0 */3 * * *를 지정하면 생성 시점부터 세 시간 간격으로 실행하는 것이 아니라 자정, 오전 3시, 오전 6시와 같이 세 시간 간격으로 실행합니다.

일정에는 목표 실행 시각을 지정합니다. Agents API는 부하를 분산하기 위해 반복 실행 시마다 짧은 무작위 지연을 추가합니다. 대상 세션이 작업 중이면 대기 시간이 더 길어질 수 있습니다.

기존 세션 이어가기

에이전트에 이전에 확인한 내용이나 메시지, 저장된 작업이 필요하면 기존 세션을 사용하세요. 예를 들어 저녁 식사를 계획하는 세션에는 사용자의 레스토랑 선호 조건과 이전에 조회한 예약 가능 여부를 보관할 수 있습니다.

다음 예시는 해당 세션에서 두 시간마다 레스토랑 예약 가능 여부를 확인합니다.

레스토랑 예약 가능 여부 확인하기
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Check restaurant reservations",
    expression="0 */2 * * *",
    timezone="America/New_York",
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check restaurant availability for our dinner plans. "
            "Compare with earlier checks and report newly available tables."
        ),
    },
)
print(automation.to_json())

호출할 때마다 저장된 지침이 같은 세션에 자동화 알림으로 전달되며, 해당 세션의 현재 에이전트 설정과 저장된 상태가 사용됩니다. 자동화 알림은 새 사용자 메시지와 별개입니다.

세션이 작업 중이면 작업을 받을 수 있을 때까지 전달을 보류합니다. 예약 실행은 진행 중인 턴을 중단하지 않으며, 아직 받지 못한 도구 결과나 승인을 대신 제공하지도 않습니다. 애플리케이션에서 여전히 필수 작업을 처리해야 합니다.

한 번만 확인하도록 예약하기

후속 작업을 한 번만 실행하려면 type: "once"와 run_at을 함께 사용하세요. 실행 시점은 미래여야 하며 Unix 타임스탬프를 초 단위 정수로 지정해야 합니다. expression이나 timezone은 포함하지 마세요.

확인 작업을 UTC 기준 2027년 1월 1일 오전 9시에 실행하도록 예약하세요.

에이전트를 한 번만 실행하도록 예약하기
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Check restaurant reply",
    run_at=1798794000,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check whether the restaurant replied about our booking. "
            "Summarize any changes to the dinner plans."
        ),
    },
)
print(automation.to_json())

일회성 일정은 한 번 실행을 마치면 더 이상 예약 실행이 남아 있지 않습니다. 이후에도 수동으로 호출할 수 있으며, 다음 후속 작업을 예약하려면 새 자동화를 만들 수 있습니다.

에이전트가 후속 작업을 예약하도록 설정하기

에이전트의 도구에 automations를 추가하면 사용자가 요청한 작업을 에이전트가 예약할 수 있습니다. 다음 예시에서는 하위 에이전트도 활성화해 기본 에이전트가 각 예약 작업을 위임하고 결과를 간략히 요약해 보관할 수 있게 합니다.

에이전트가 작업을 예약하도록 설정하기
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "Use automations to schedule tasks requested by the user. "
            "Delegate each scheduled task to a subagent and ask for a concise result. "
            "Keep the goal, schedule, and useful summaries in the main session. "
            "Adjust or stop schedules when the user asks."
        ),
        "multi_agent": {"enabled": True},
        "tools": [{"type": "automations"}],
    },
    environment={"type": "openai_hosted"},
    input=(
        "Every day at 10 AM in America/New_York, review the goals we discuss here "
        "and suggest the next actions I could take."
    ),
)
print(session.id)

이렇게 설정하면 에이전트가 자체 자동화를 생성하고, 목록이나 개별 자동화를 조회하고, 수정하거나 일시 중지하거나 재개하거나 삭제할 수 있습니다. Agents API는 현재 세션을 대상으로 설정합니다. 에이전트는 일회성 실행이나 주기적 실행을 예약할 수 있지만, 이 도구로 새 세션을 시작하거나 다른 세션의 자동화를 관리할 수는 없습니다.

이 도구로 접근할 수 있는 자동화는 에이전트가 현재 세션에서 만든 것뿐입니다. 애플리케이션은 API를 통해 이러한 자동화와 애플리케이션이 직접 만든 자동화를 함께 관리할 수 있습니다. Agents API는 생성 주체를 created_by에 기록합니다. 생성 요청에 이 필드를 포함하지 마세요.

기본적으로 에이전트에는 이 도구가 없습니다. 애플리케이션은 도구를 활성화하지 않아도 작업을 예약할 수 있습니다. 에이전트 설정에서 도구를 제거해도 저장된 일정은 삭제되지 않습니다. 필요하면 API를 통해 일정을 일시 중지하거나 삭제하세요.

반복 작업의 세부 내용을 기본 세션의 컨텍스트에서 제외하기

지속적으로 수행할 목표가 있다면 다중 에이전트 오케스트레이션을 활성화하세요. 설정값은 agent.multi_agent.enabled: true입니다. 기본 에이전트에 목표와 일정을 유지하고 각 작업을 하위 에이전트에 위임한 뒤 결과를 간략히 보관하도록 지시하세요. 이렇게 하면 반복 조회에서 나온 상세한 도구 출력이 기본 세션의 컨텍스트 윈도우에 쌓이지 않습니다.

예를 들어 기본 에이전트의 지침에 다음 내용을 포함하세요.

각 예약 작업을 하위 에이전트에 위임하세요. 목표와 이전에 확인한 관련 내용을 전달하고 간결한 결과를 요청하세요. 결과를 검토해 유용한 내용을 요약해 보관하고, 일정을 계속 진행할지, 변경할지, 중단할지 결정하세요.

automations 도구는 일정을 관리합니다. 에이전트가 예약 작업을 수행하는 데 필요한 다른 도구와 데이터 접근 권한도 유지하세요.

앱에서 온보딩 후속 작업 예약하기

애플리케이션은 자체 이벤트가 발생했을 때도 일정을 만들 수 있습니다. 예를 들어 사용자가 가입하면 온보딩 세션을 시작하고 첫 후속 작업을 48시간 뒤로 예약하세요.

온보딩 후속 작업 예약하기
import time

from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Onboarding follow-up",
    run_at=int(time.time()) + 48 * 60 * 60,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Review onboarding progress and send the next onboarding message "
            "if the user has not completed onboarding."
        ),
    },
)
print(automation.to_json())

후속 작업을 마칠 때마다 애플리케이션에서 다음 작업을 48시간 뒤로 예약할 수 있습니다. 온보딩이 끝나거나 사용자가 후속 작업을 원하지 않으면 중단하고 대기 중인 후속 작업을 삭제하세요. 이 간격에는 일회성 일정을 사용하세요. cron 표현식에서 월의 일자를 지정하는 방식으로는 달이 바뀌어도 48시간마다 반복되는 일정을 표현할 수 없습니다.

온보딩 에이전트에는 온보딩 진행 상황과 애플리케이션의 메시지 전송 도구에 대한 접근 권한이 필요합니다. 자동화를 만들면 작업이 예약되며 메시지가 즉시 전송되지는 않습니다.

시험 실행하고 전달 상태 확인하기

저장된 자동화를 즉시 테스트하려면 요청 본문 없이 POST /v1/agents/automations/auto_123/invocations를 보내세요. 수동 호출은 저장된 일정을 변경하지 않으며 일회성 일정의 예약 실행 횟수를 차감하지도 않습니다. 일정이 일시 중지된 상태에서도 수동 호출이 가능합니다.

응답으로 받은 호출 ID를 저장하세요. GET /v1/agents/automations/auto_123/invocations/ainv_123으로 해당 호출을 조회하거나 GET /v1/agents/automations/auto_123/invocations로 전달 기록 목록을 조회하세요.

지난 실행 내역을 한눈에 보려면 해당 자동화의 호출 목록을 조회하세요.

자동화 호출 모니터링하기
import OpenAI from "openai";

const client = new OpenAI();
for await (const invocation of client.beta.agents.automations.invocations.list(
  "auto_123"
)) {
  console.log(invocation.id, invocation.status, invocation.session_id);
}

호출 기록에는 이미 생성된 호출이 포함되며, 앞으로 예정된 모든 실행이 표시되지는 않습니다. 다음 필드를 확인하세요.

필드 확인할 내용
status 초기 상태는 queued이며 전달에 성공하면 completed로 바뀝니다.
session_id 전달 후 추적할 세션의 ID입니다. 세션을 사용할 수 있게 되기 전에는 null일 수 있습니다.
source.type 수동 호출이면 manual, 예약 실행이면 automation입니다.
scheduled_at 실행이 예정된 시각입니다. 수동 호출이면 null입니다.

전달이 완료되었다고 해서 에이전트의 작업까지 완료된 것은 아닙니다. 새 세션의 경우 세션이 초기 입력을 수락했다는 뜻입니다. 기존 세션의 경우 세션이 알림과 작업 시작 요청을 수락했다는 뜻입니다.

호출의 session_id를 사용해 세션 이벤트를 추적하고 해당 턴의 결과를 확인하세요.

자동화는 작업을 예약합니다. 세션 출력을 표시하고 사용자에게 알림을 보내는 역할은 애플리케이션이 담당합니다.

일정 변경 또는 중단하기

자동화를 조회하려면 GET /v1/agents/automations/auto_123을 사용하세요. 프로젝트의 자동화 목록은 GET /v1/agents/automations로 조회하세요. session_id=sess_123을 추가하면 특정 기존 세션을 대상으로 하는 자동화를 찾을 수 있습니다.

반복 확인 시각을 오전 11시로 변경하려면 cron 표현식을 수정하세요.

일정 변경하기
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.update(
    automation_id="auto_123",
    expression="0 11 * * *",
)
print(automation.to_json())

생략한 필드는 기존 값을 유지합니다. target을 지정하면 대상 설정 전체를 교체하므로 필수 필드를 모두 포함하고 기존 유형을 유지하세요. 알림 문구는 target.instructions에서, 초기 메시지는 target.input에서 수정하세요. 에이전트가 만든 자동화는 해당 에이전트가 자동화를 만든 세션을 대상으로 유지해야 합니다.

다음 예약 시각 전에 일정을 변경하세요. 변경 사항은 이후에 생성되는 호출에 적용됩니다. 이미 대기열에 있는 호출은 생성 시 저장된 대상과 입력을 그대로 사용합니다.

다음 작업은 요청 본문 없이 실행하세요.

목적 작업 효과
예약 작업 일시 중지 POST /v1/agents/automations/auto_123/pause 대기 중인 예약 작업의 전달을 보류합니다. 수동 호출은 계속 사용할 수 있습니다.
예약 작업 재개 POST /v1/agents/automations/auto_123/resume 저장된 일정을 다시 활성화합니다.
일정 삭제 DELETE /v1/agents/automations/auto_123 이후 예약 호출과 수동 호출을 모두 차단합니다.

자동화를 일시 중지하거나 삭제해도 세션이 이미 수락한 작업은 중단되지 않으며 세션도 삭제되지 않습니다. 이미 전달 중인 작업은 대상 세션에 도달할 수 있습니다. 현재 작업을 중단하려면 진행 중인 턴을 취소하세요.

일회성 자동화가 일시 중지된 동안 예약 시각이 지났다면 재개하기 전에 run_at을 새로운 미래 시각으로 설정하세요. 실행을 마친 일회성 자동화는 일시 중지하거나 재개할 수 없습니다. 다른 후속 작업을 예약하려면 새 자동화를 만드세요.