세션 작업

세션이 존재하면 이러한 작업을 사용하여 세션을 읽고, 업데이트하고, 보관하거나 삭제할 수 있습니다. 세션을 생성하고 작업을 보내는 방법은 세션 시작하기를 참조하세요.

세션 상태

세션은 다음 상태를 거쳐 진행됩니다. 세션 수명 주기에 대해서는 세션 시작하기를 참조하세요.

에이전트 구성 업데이트

새 에이전트 버전을 생성하지 않고도 세션 도중에 세션의 agent.tools 및 agent.mcp_servers를 업데이트할 수 있으며, 여기에는 권한 정책과 도메인 필터 같은 도구별 웹 설정이 포함됩니다. 업데이트는 세션에 국한되며 기반 에이전트로 다시 전파되지 않습니다. 업데이트된 allowed_domains 및 blocked_domains는 세션의 나머지 기간 동안 적용됩니다.

세션이 생성된 후에는 에이전트의 tools와 mcp_servers만 변경할 수 있습니다. 에이전트의 값과 다른 model, system 또는 skills 값으로 세션을 실행하려면 세션을 생성할 때 에이전트 구성 재정의를 사용하세요. inference_geo 고정을 포함한 에이전트의 모델 구성 역시 세션 도중에 변경할 수 없습니다. 에이전트를 저장할 때 고정을 설정하거나, 세션을 생성할 때 model 재정의를 통해 단일 세션에 대해 설정하거나 해제하세요. 에이전트에 구성된 system 필드는 세션 수명 동안 고정됩니다. 이를 지원하는 모델에서는 system.message 이벤트를 전송하여 세션 도중에도 시스템 수준의 지침을 추가할 수 있습니다.

tools 또는 mcp_servers 업데이트의 의미는 전체 교체입니다. 즉, 제공된 배열이 새 값이 됩니다. 기존 항목을 유지하려면 세션을 GET하고 배열을 수정한 다음 다시 POST하세요.

에이전트를 업데이트하려면 세션이 idle 상태여야 합니다. 세션이 실행 중일 때 에이전트를 업데이트하려면 user.interrupt 이벤트를 단독으로 전송하고 세션이 idle 상태가 될 때까지 기다리세요.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
  tools:
    - type: agent_toolset_20260401
    - type: mcp_toolset
      mcp_server_name: linear
  mcp_servers:
    - type: url
      name: linear
      url: https://mcp.linear.app/sse
YAML

세션 예산 업데이트

예산과 함께 생성된 세션은 두 가지 종류의 예산 업데이트를 허용합니다. 새 max_list_cost로 한도를 교체하는 것과, budget을 null로 설정하여 한도를 제거하는 것입니다. 두 경우 모두 세션이 한도에 도달하여 일시 중지된 작업을 자동으로 재개합니다. 교체 한도는 현재 한도보다 높거나 낮을 수 있지만 세션이 소비한 정가 비용보다 반드시 커야 하며, 제거는 단방향입니다. null이 아닌 budget은 현재 예산이 있는 세션에서만 허용되므로, 제거된 예산을 다시 추가하거나 예산 없이 생성된 세션에 예산을 추가할 수 없습니다. 요청 예시, 오류 동작, 정가 비용에 포함되는 항목에 대해서는 세션 예산을 참조하세요.

세션 조회

ant beta:sessions retrieve --session-id "$SESSION_ID"

세션 나열

GET /v1/sessions의 결과는 페이지로 나뉩니다. limit 쿼리 매개변수를 사용하여 페이지 크기를 제어하세요. 각 응답에는 next_page 커서가 포함되며, 다음 요청에서 이를 page 매개변수로 전달하면 다음 페이지를 가져올 수 있습니다. 더 이상 결과가 없으면 next_page는 null입니다.

이전 페이지로 돌아가려면 prev_page를 page 매개변수로 전달하세요. 첫 페이지에 있을 때 prev_page는 null입니다.

page 커서는 불투명하며 이를 생성한 요청의 order를 인코딩합니다. order 쿼리 매개변수는 결과의 정렬 방향을 생성 시간 기준 asc 또는 desc로 설정하며, 기본값은 desc(최신순)입니다. 다른 order로 커서를 재사용하면 400 오류가 반환되며, 커서의 위치를 제외하도록 created_at 필터를 변경하는 경우에도 마찬가지입니다. 나머지 필터와 limit을 포함한 다른 쿼리 매개변수는 페이지 요청 간에 변경할 수 있습니다. 목록 엔드포인트 전반에서 공유되는 페이지네이션 필드에 대해서는 페이지네이션을 참조하세요.

# --format raw는 prev_page 및 next_page 커서가 포함된 하나의 페이지 봉투를
# 반환합니다. 기본 출력은 자동 페이지네이션하며 세션만 출력합니다.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# next_page 커서를 --page로 다시 전달하여 다음 페이지를 가져옵니다.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# 해당 응답의 prev_page를 --page로 전달하여 같은 방식으로 되돌아갑니다.

세션 보관

세션을 보관하면 기록을 보존하면서 새 이벤트가 전송되는 것을 방지할 수 있습니다. running 상태의 세션은 보관할 수 없습니다. 보관하려면 user.interrupt 이벤트를 단독으로 전송하고 세션이 idle 상태가 될 때까지 기다리세요.

ant beta:sessions archive \
  --session-id "$SESSION_ID"

세션 삭제

세션을 삭제하면 해당 레코드, 이벤트 및 연결된 샌드박스가 영구적으로 제거됩니다. running 상태의 세션은 삭제할 수 없습니다. 삭제하려면 user.interrupt 이벤트를 단독으로 전송하고 세션이 idle 상태가 될 때까지 기다리세요.

메모리 저장소, 볼트, 스킬, 환경 및 에이전트는 독립적인 리소스이며 세션 삭제의 영향을 받지 않습니다. Files API를 통해 업로드한 파일도 영향을 받지 않지만, 세션 자체가 생성한 파일은 해당 세션에 범위가 한정되어 있어 파일 시스템과 함께 영구적으로 삭제됩니다. 세션을 삭제하기 전에 보관해야 할 항목을 모두 다운로드하세요. 마지막 턴이 끝날 때 작성된 출력 파일은 세션이 idle 상태가 된 후 세션의 파일 목록에 나타나기까지 몇 초가 걸릴 수 있으므로, 먼저 예상하는 파일이 목록에 있는지 확인하세요.

ant beta:sessions delete \
  --session-id "$SESSION_ID"