OpenAI의 Codex cloud 문서도 같은 방향을 보여줍니다. Codex는 cloud 환경에서 백그라운드 작업을 수행하고, 여러 작업을 병렬로 처리하며, 웹·IDE·iOS·GitHub 같은 경로에서 위임될 수 있습니다. Google도 2026년 5월 26일 Jules 공개 출시를 알리며 베타 기간 동안 공개적으로 공유된 코드 개선이 14만 건을 넘었고, Gemini 2.5 기반의 구조화된 사용 tier를 제시했습니다. 2025년의 Jules public beta 발표에서 이미 비동기 cloud VM, GitHub 통합, plan/diff 제시를 강조했는데, 이제 이 흐름이 실험에서 제품 운영 표면으로 넘어오고 있습니다.

이 글에서는 이 흐름을 Agent Invocation API라고 부르겠습니다. 채팅창에서 사람이 “이거 고쳐줘"라고 말하는 단계를 넘어, 내부 개발자 포털, 릴리스 스크립트, 보안 triage, 코드 검색 시스템, 마이그레이션 도구가 에이전트 작업을 호출하는 구조입니다. 이 관점은 Background Agent Session, Task Graph Runtime, Remote Agent Control Plane, Agentic PR Governance와 이어집니다. 핵심 질문은 “어떤 모델이 코드를 잘 쓰는가"보다 누가 어떤 조건으로 에이전트 작업을 생성하고, 어디서 멈추며, 무엇을 증거로 남기는가입니다.

이 글에서 얻는 것

• Agent Invocation API가 단순 채팅 자동화가 아니라 비동기 작업 큐와 비슷한 운영 문제인 이유를 이해할 수 있습니다.
• agent task template, idempotency key, progress state, artifact, budget, human gate를 어떤 순서로 설계할지 기준을 얻습니다.
• 내부 포털, 릴리스 자동화, 대량 refactor, 보안/품질 backlog 처리에 에이전트를 붙일 때의 위험 기준을 정리할 수 있습니다.
• 코딩 에이전트 API를 도입하기 전 필요한 체크리스트를 숫자와 조건 중심으로 만들 수 있습니다.

핵심 개념/이슈

1) 에이전트 호출은 prompt 전송이 아니라 작업 생성이다

API로 에이전트를 호출한다고 하면 많은 팀이 “프롬프트 문자열을 보내면 되겠네"라고 생각합니다. 하지만 실제 운영에서 prompt는 일부일 뿐입니다. 작업에는 정체성과 범위가 있어야 합니다.

최소 task envelope은 아래처럼 잡는 편이 좋습니다.

agent_task:
  task_id: "agt_20260527_001"
  requester: "developer-portal"
  repo: "payments-api"
  base_ref: "main"
  task_type: "draft_pr"
  risk_label: "medium"
  prompt_template: "add_missing_tests_v1"
  allowed_paths:
    - "src/test/**"
    - "src/main/java/com/acme/payments/**"
  blocked_paths:
    - "infra/**"
    - ".github/workflows/**"
  validation_commands:
    - "./gradlew test --tests PaymentRetryTest"
  create_pull_request: true
  max_files_changed: 8
  budget:
    max_minutes: 30
    max_sessions: 1

이 구조가 없으면 같은 API라도 위험도가 완전히 달라집니다. “테스트 추가"와 “결제 로직 수정"은 모두 prompt 한 줄로 표현될 수 있지만, 권한과 검증 기준은 달라야 합니다. 따라서 Agent Invocation API 앞에는 내부 template 계층이 필요합니다. 사용자가 자유문장을 바로 API에 넣는 방식은 초기 데모에는 빠르지만, 운영에서는 범위 초과와 중복 실행을 만들기 쉽습니다.

2) agent task는 idempotency가 필요하다

API 호출이 생기면 재시도도 생깁니다. 네트워크 timeout, 내부 포털 retry, cron 재실행, webhook 중복 전달 때문에 같은 agent task가 두 번 생성될 수 있습니다. 사람이 채팅에서 한 번 더 요청하면 눈치챌 수 있지만, 자동화에서는 branch, PR, comment, CI run이 중복으로 쌓입니다.

그래서 task 생성에는 idempotency key가 필요합니다. 예를 들어 아래 조합을 사용할 수 있습니다.

idempotency_key =
  hash(task_template + repo + base_ref + issue_id + normalized_scope + requested_at_bucket)

같은 key가 10분 안에 다시 들어오면 새 작업을 만들지 않고 기존 task URL을 반환합니다. 릴리스 노트 생성처럼 매일 반복되는 작업은 날짜를 key에 포함하고, 이슈 기반 수정은 issue id와 target repo를 포함합니다. 대량 fan-out 작업은 parent batch id를 둡니다.

중복 방지의 목적은 비용 절감만이 아닙니다. 같은 에이전트가 같은 이슈에 PR을 두 개 열면 리뷰어는 어느 쪽이 최신인지 판단해야 하고, CI 자원도 낭비됩니다. 이 문제는 Execution Receipt에서 말한 duplicate suppression과 같은 축입니다.

3) progress state와 artifact 계약이 있어야 추적 가능하다

에이전트 작업이 백그라운드로 들어가면 “지금 뭘 하고 있나"가 중요해집니다. 단순히 running 하나로는 부족합니다. 운영자가 필요한 것은 중간 상태와 산출물입니다.

권장 상태:

artifact도 표준화해야 합니다. 최소한 diff/branch, PR URL, 테스트 결과, 실패한 명령, work log, 비용·시간, 사용 model, 변경 파일 목록이 남아야 합니다. 이 기준은 Agent Artifact Registry와 바로 연결됩니다. 에이전트가 “완료했습니다"라고 말해도 artifact가 없으면 운영적으로는 완료가 아닙니다.

4) fan-out 자동화는 리뷰 큐와 CI 용량을 먼저 때린다

GitHub의 Agent tasks API 발표 예시처럼 API 호출형 에이전트는 여러 저장소에 refactor나 migration을 fan-out하기 좋습니다. 사내 포털에서 “모든 서비스에 새 logging wrapper 적용” 버튼을 누르면 50개 repo에 agent task를 만들 수 있습니다. 매력적이지만 위험도 큽니다.

대량 호출에는 별도 제한이 필요합니다.

• repo별 동시 agent task: 1~2개
• 조직 전체 동시 task: CI capacity의 20~30% 이하부터 시작
• 한 batch의 draft PR 생성 상한: 10개부터 시작
• 동일 template 일일 실행 한도: 예를 들어 50 tasks/day
• medium 이상 risk는 batch당 sample PR 1~3개 승인 후 확대
• 실패율 20% 초과 또는 CI queue p95 2배 악화 시 batch pause

에이전트가 작업을 빨리 만들수록 사람 리뷰와 CI가 병목이 됩니다. 그래서 Agent Invocation API는 AI PR Review Backlog OS와 같이 봐야 합니다. 자동화의 성공 지표는 생성된 PR 수가 아니라 merge 가능한 고품질 PR 비율입니다.

5) model 선택도 정책의 일부가 된다

GitHub는 2026년 5월 18일 Copilot cloud agent에 더 빠르고 저렴한 모델 옵션을 추가하며 작업 성격에 맞춰 모델을 고를 수 있음을 강조했습니다. 이 변화는 단순 비용 옵션이 아닙니다. Agent Invocation API에서는 model selection이 정책이 됩니다.

추천 기준은 아래처럼 나눌 수 있습니다.

중요한 것은 모델 이름보다 작업 등급입니다. 같은 모델이라도 create_pull_request=false인 계획 작업과, create_pull_request=true인 코드 변경 작업은 위험도가 다릅니다. 모델 정책은 task template, repo risk, 변경 범위, budget과 함께 평가해야 합니다.

실무 적용

1) 내부 developer portal에 agent task template을 둔다

처음부터 모든 자유 요청을 API로 열지 않습니다. 반복 작업 3~5개만 template으로 시작합니다.

• “이슈 하나에 대한 테스트 추가”
• “deprecated API 사용처 조사”
• “릴리스 노트 초안 작성”
• “특정 lint rule 자동 수정”
• “문서 예제 최신화”

각 template에는 허용 repo, 허용 path, 생성 가능한 artifact, 검증 명령, budget, owner를 둡니다. 사용자는 자유 prompt를 넣기보다 template 변수를 채웁니다. 예를 들어 issue_url, target_module, validation_command, create_pr 정도입니다. 이렇게 하면 API 호출형 에이전트가 제품 기능처럼 관리됩니다.

2) read-only와 write task를 분리한다

가장 안전한 도입 순서는 read-only입니다. “이 repo에서 deprecated API 사용처를 찾아 영향도를 정리해줘” 같은 작업은 branch나 PR을 만들지 않아도 됩니다. 다음 단계는 draft PR입니다. 그 다음에만 제한된 write automation을 검토합니다.

권한 단계:

1. R0 read-only: 코드 읽기, 요약, 영향 분석
2. R1 draft artifact: plan, patch proposal, test list
3. R2 branch/draft PR: isolated branch 생성, required checks 실행
4. R3 external side effect: issue comment, release note, package publish 준비
5. R4 production-affecting action: 배포, 권한, 데이터 변경

R0~R2는 자동화 후보가 될 수 있지만, R3 이상은 Remote Agent Control Plane처럼 승인과 회수 경로를 가져야 합니다. R4는 기본적으로 사람이 최종 실행합니다.

3) result inbox를 만든다

에이전트 작업은 생성보다 수거가 중요합니다. 내부 포털이나 Slack 알림에 “완료"만 보내면 팀은 다시 링크를 열고, PR을 찾고, 로그를 확인해야 합니다. 좋은 result inbox는 아래 정보를 한 화면에 모읍니다.

• task name, repo, requester, risk label
• current state와 소요 시간
• branch/PR/artifact 링크
• validation summary
• failed commands
• changed files count
• next action: review, approve plan, retry, cancel, archive

이 inbox가 있어야 API 호출형 에이전트가 조직에 실제로 들어옵니다. 그렇지 않으면 agent task는 또 하나의 알림 소스가 되고, 완료된 일과 검토해야 할 일이 섞입니다.

트레이드오프/주의점

첫째, API 호출은 편하지만 실수도 빨라집니다. 사람이 채팅에서 한 번 실행하던 일을 cron이나 포털이 수십 번 실행할 수 있습니다. 그래서 기본값은 allowlist template, 낮은 concurrency, draft PR이어야 합니다.

둘째, agent task는 CI 비용을 씁니다. 작은 모델을 선택해도 테스트, 빌드, preview 환경 비용이 더 클 수 있습니다. cost metric은 모델 토큰만 보지 말고 task당 CI minutes, 리뷰어 minutes, 재작업률, merge까지 걸린 시간을 같이 봐야 합니다.

셋째, GitHub App token, personal access token, OAuth token 같은 인증 방식은 운영 책임이 다릅니다. task를 시작하는 주체가 사람인지 내부 앱인지 명확해야 감사가 됩니다. “누가 시켰는가"와 “누가 merge했는가"는 분리해 기록합니다.

넷째, 외부 에이전트 런타임은 네트워크와 비밀값 경계를 가집니다. Codex cloud의 agent internet access 문서도 인터넷 접근이 prompt injection, exfiltration, malware, license risk를 만들 수 있다고 설명합니다. 에이전트가 패키지를 설치하거나 외부 문서를 읽는다면 Agent Sandbox Egress Policy와 같은 allowlist·budget·audit가 필요합니다.

다섯째, Agent Invocation API를 붙인다고 플랫폼팀 일이 줄어들지는 않습니다. 오히려 초기에는 template, policy, result inbox, evidence, budget, retry, cancel, cleanup을 만들어야 해서 일이 늘어납니다. 하지만 이 작업은 에이전트 생성량이 늘어날수록 회수됩니다. 기준 없이 늘어난 자동화는 생산성이 아니라 운영 부채입니다.

체크리스트 또는 연습

• agent task를 직접 prompt가 아니라 승인된 template으로 생성한다.
• task마다 task_id, requester, repo, base_ref, risk_label, idempotency_key가 있다.
• 같은 idempotency key 재호출 시 새 PR을 만들지 않는다.
• read-only, draft PR, external side effect 권한이 분리되어 있다.
• repo별/조직별 동시 task와 일일 budget이 있다.
• task result에 diff, 테스트 결과, 실패 명령, artifact, 비용/시간이 남는다.
• medium 이상 risk는 plan 승인 또는 CODEOWNERS review를 요구한다.
• fan-out batch는 sample task 성공 후 확대된다.

연습으로 내부 자동화 후보 3개를 골라 보세요. 각각을 R0 read-only, R1 draft artifact, R2 draft PR, R3 external side effect로 분류하고, 실행 한도를 숫자로 적습니다. 예를 들어 “deprecated API 조사: R0, 하루 30개 repo”, “테스트 추가 PR: R2, repo당 동시 1개”, “릴리스 노트 초안: R1, release branch당 1개"처럼 쓰면 됩니다. 이 표를 만들지 못하면 아직 Agent Invocation API를 열기보다 작업 정의를 먼저 해야 합니다.

정리하면 Agent Invocation API의 핵심은 에이전트를 더 쉽게 부르는 것이 아닙니다. 에이전트를 호출 가능한 운영 자원으로 다루는 것입니다. 작업은 생성되고, 추적되고, 검증되고, 취소되고, 재시도되고, 리뷰 큐로 흘러갑니다. 좋은 팀은 이 흐름을 채팅 프롬프트가 아니라 task queue, artifact registry, PR governance, cost budget으로 설계할 것입니다.