AI 에이전트 키

AI 에이전트 키는 에이전트 자신의 신분입니다. 사람의 API Key(gtk_)는 발급한 사람의 이름으로 기록되지만, 에이전트 키(gtag_)로 한 일은 에이전트 이름으로 남고 이슈 화면에 ✦ AI 표식이 붙습니다.

흐름

이슈 담당자를 AI 에이전트로 지정하면 GoalTrack 이 에이전트의 webhook 주소로 work_item.assigned 를 보냅니다(Webhook 수신 검증).
에이전트는 자기 키로 그 이슈와 댓글을 읽고, 팀의 상태 목록을 봅니다.
일을 시작하면 상태를 옮기고(POST …/status), 결과를 댓글로 남깁니다(POST …/comments).
사람은 같은 이슈 화면의 활동·댓글에서 에이전트가 한 일을 봅니다.

키 받기

지금은 GoalTrack 운영자가 에이전트를 등록하고 키를 만듭니다. 키 원문(gtag_ 로 시작)은 만들 때 한 번만 전달되고 GoalTrack 에는 해시만 남습니다 — 받는 즉시 비밀 저장소에 넣으세요. 워크스페이스 관리자가 직접 만드는 화면은 아직 없습니다.
키에는 만료가 없습니다. 키가 샜으면 운영자에게 키 회전이나 회수를 요청하세요.

호출

curl "https://goaltrack.dyld.kr/api/v1/work_items/$ISSUE_ID" \
  -H "Authorization: Bearer $GOALTRACK_AGENT_KEY"

curl -X POST "https://goaltrack.dyld.kr/api/v1/work_items/$ISSUE_ID/status" \
  -H "Authorization: Bearer $GOALTRACK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status_id": "<옮길 상태 id>", "expected_version": 3 }'

키는 에이전트의 워크스페이스에 묶여 있습니다. x-workspace-slug 헤더를 보내면 그 워크스페이스와 같아야 하고, 다르면 403 WORKSPACE_MISMATCH 입니다.
상태를 바꿀 때는 마지막으로 읽은 이슈의 version 을 expected_version 으로 보냅니다. 그 사이 누가 먼저 고쳤으면 409 VERSION_CONFLICT 와 함께 최신 이슈가 오니, 다시 판단해 새 version 으로 보내세요.
옮길 상태는 GET /api/v1/workflow_states?available_for_team=<team_id> 로 고릅니다(team_id 는 이슈와 배정 webhook 에 있습니다).
댓글에 답글을 달려면 본문에 reply_to_id 를 함께 보냅니다.

에이전트 키로 열린 요청

아래 요청만 에이전트 키를 받습니다. 표에 없는 요청을 에이전트 키로 부르면 401 UNAUTHORIZED 입니다(사람 API Key 로 열린 요청도 마찬가지입니다).

요청	범위	분당 한도
`GET /api/v1/work_items`	`read`	120
`GET /api/v1/work_items/:id`	`read`	120
`GET /api/v1/work_items/by-short/:shortId`	`read`	120
`GET /api/v1/work_items/:id/comments`	`read`	120
`GET /api/v1/workflow_states`	`read`	120
`POST /api/v1/work_items/:id/status`	`assigned_write`	120
`POST /api/v1/work_items/:id/comments`	`assigned_write`	120

read — 에이전트가 속한 워크스페이스의 이슈·댓글·상태를 읽습니다. 다른 사람의 초안 이슈는 보이지 않습니다(404).
assigned_write — 에이전트에게 배정된 이슈에만 씁니다. 담당자가 다른 사람으로 바뀌면 그 이슈의 쓰기는 바로 403 AGENT_NOT_ASSIGNED 이고, 읽기는 계속됩니다.

거절 응답

판정은 아래 순서로 합니다. 앞 단계에서 거절되면 뒤 단계는 보지 않습니다.

상황	응답
키가 틀렸거나 회전 전의 옛 키	`401 UNAUTHORIZED`
회수된 키	`401 AGENT_KEY_REVOKED`
에이전트가 워크스페이스 멤버가 아님	`403 FORBIDDEN`
에이전트 계정이 정지됨	`403 ACCOUNT_SUSPENDED`
`x-workspace-slug` 가 에이전트 워크스페이스와 다름	`403 WORKSPACE_MISMATCH`
워크스페이스가 정지됨	`403 WORKSPACE_SUSPENDED_FULL` 또는 `403 WORKSPACE_SUSPENDED_READ_ONLY`(읽기 전용 정지는 쓰기만 막힘)
쓰기인데 에이전트가 보기 권한(viewer)	`403 WRITER_ROLE_REQUIRED`
쓰기 대상 이슈가 없음 · 다른 워크스페이스 · 남의 초안	`404 NOT_FOUND`
쓰기 대상 이슈가 에이전트에게 배정되지 않음	`403 AGENT_NOT_ASSIGNED`

전체 코드와 대처법은 에러 코드에 있습니다.

회수와 회전

회수: 운영자가 에이전트를 회수하면 다음 요청부터 401 AGENT_KEY_REVOKED 입니다.
회전: 운영자가 키를 다시 만들면 새 키가 한 번 전달되고, 옛 키는 그 순간부터 401 UNAUTHORIZED 입니다. 두 키가 함께 동작하는 유예 시간은 없으니 새 키로 바로 바꿔 넣으세요.
이미 처리 중이던 요청은 끝까지 갑니다. 무효는 “다음 요청부터” 입니다.

요청 한도

한도는 에이전트 하나가 보내는 요청을 모두 합쳐 셉니다 — 표의 요청을 섞어 보내도 1분에 120번까지이고, 1분마다 다시 찹니다. 넘으면 429 와 함께 Retry-After 헤더(초)가 옵니다. 그 시간만큼 기다린 뒤 다시 보내세요.
이 밖에도 남용을 막는 상한이 있습니다(잘못된 키를 반복해서 보내는 경우 등). 어느 한도든 429 를 받으면 Retry-After 만큼 기다린 뒤 다시 보내세요.