Agent Engine SDK ADK

일시 중단 및 재개

작성자는 공식 생성자 `FunctionTool(..., require_confirmation=True) <를 사용하여 에이전트 빌더에서 네이티브 ADK 대기를 구성합니다.https://adk.dev/graphs/man-input/#tool-confirmation-approval-prompts-in-llm-agents >`__ 및 LongRunningFunctionTool. 원시 @app.tool 함수가 아닌 app.tools()에서 콜러블을 전달합니다: @app.tool은(는) 도구만 등록합니다. app.tools()는 Atlas Agent Engine 보안 래퍼를 적용합니다. Atlas Agent Engine은 각 대기를 하나의 OE 활동으로 기록하고 하나의 명령으로 전체 경계를 확정합니다. Atlas Agent Engine 인터럽트 ID는 해당 활동 ID이며, ADK 함수 호출 ID가 아닙니다. 계속하려면 전체 resume_map 하나가 필요합니다. 원본 사용자 메시지를 다시 탐색하는 새로운 시도입니다. OE는 기록된 답변 반환합니다. 어댑터는 이 실행의 함수 호출 ID로 키가 지정된 한 개의 FunctionResponse 부분 배치 를 ADK에 공급합니다. Atlas Agent Engine app.suspend()이(가) 없습니다. 확인 답변 은 ADK의 {confirmed: true|false} 객체 입니다. RequestInput 답변 ADK의 FunctionResponse.response 딕셔너리가 허용하는 모든 것, 즉 JSON 객체 또는 어댑터가 {result: ...}로 래핑하는 null이 아닌 스칼라/ 배열 입니다. JSON null 은 (답변 아닙니다.

attempt 1: original message → ADK runs to quiescence → OE frontier 1 SUSPENDED
attempt 2: replay frontier 1 → COMPLETED → commit step 1 → continue ADK
           → frontier 2 SUSPENDED
attempt 3: replay step 1 → replay frontier 2 → COMPLETED → commit step 2 → continue

어댑터는 ADK BaseAgent 또는 ADK 2 Workflow를 허용합니다. ADK는 LangGraph 스타일의 슈퍼스탭 수명 주기를 정의하지 않습니다. 따라서 Atlas Agent Engine은 조용한 조정 프론티어에서만 단계를 도입합니다: 해당 프론티어의 모든 대기는 원자적으로 조인되고, 해결된 프론티어가 해당 단계를 커밋하고, 다음 Runner.run_async 연속이 다음 단계를 시작합니다.

워크플로 및 에이전트 경로

ADK는 다양한 구성 API를 통해 Workflow 구성 및 에이전트 협업을 노출하지만, 구성된 실행은 동일한 런타임 프리미티브에서 충족됩니다: 워크플로 노드와 에이전트는 모두 BaseNode 인스턴스이며, ADK는 각 실행 하나의 표준 Context.node_path를 할당합니다. 어댑터는 해당 경로 하나를 OE 작업 경로에 매핑합니다. 모델 텍스트나 세션 이벤트에서 에이전트 조상을 재구성하지 않습니다.

지속형 형 어댑터를 사용하려면 애플리케이션 구성 시 전체 워크플로 및 에이전트 토폴로지 필요합니다. 이는 지속형 LangGraph 그래프 어댑터와 동일한 정적 토폴로지 제약 조건으로, 외부 작업이 이미 시작된 후에는 임의의 런타임 제어 흐름을 지속형 그래프 경계로 처리할 수 없습니다.

ADK는 노드 를 실행 전에 표준 Context.node_path을(를) 할당합니다. ADK는 동일한 값을 워크플로 부기에 사용하고 방출된 이벤트에 Event.node_info.path로 기록합니다. 어댑터는 공개 BaseNode.run 경계를 래핑하여 모델 및 도구 활동 허용이 이벤트 존재하기 전에 경로를 사용할 수 있도록 합니다.

ADK node path: outer@1/inner@1/review@1
OE path:       agent -> inner -> review

구성된 ADK 루트(outer@1)는 OE의 기존 agent 루트에 매핑됩니다. 나머지 세그먼트는 하위 경계가 되며 전체 ADK 접두사는 어커런스 키로 유지됩니다.

inner occurrence:  outer@1/inner@1
review occurrence: outer@1/inner@1/review@1

병렬 left 및 right의 경우, 각 노드 래퍼는 요청-로컬 컨텍스트에서 자체 표준 경로를 바인딩하므로 완료 순서가 OE ID를 교환할 수 없습니다. review가 호출한 도구는 review 범위를 상속합니다. review가 대기를 내보내면 해당 이벤트 동일한 경로를 전달하며 일시 중단은 라이브 노드 범위가 종료된 후 동일한 경계를 기록합니다. ID는 전역 이름 조회가 아닌 전체 경로에서 가져오기 때문에 서로 다른 워크플로 상위 항목 아래에 있는 동일한 리프 이름도 구별됩니다. 잘못된 노드 경로와 노드 경로가 없는 대기 이벤트는 명시적으로 실패합니다.

configured: router -> reviewer -> specialist
ADK path:   router@1/reviewer@1/specialist@1
OE path:    agent -> reviewer -> specialist

agent root:       router agent -> reviewer -> specialist
composed:  outer Workflow -> router agent -> reviewer -> specialist

턴 레벨 되감기

App.runner Atlas Agent Engine의 안정적인 공개 ADK 러너입니다. rewind_async() 메서드는 Google의 문서화된 인수 이름을 유지하고 rewind_before_invocation_id를 OE 세션 브랜치에 직접 매핑합니다.

branch = await app.runner.rewind_async(
    user_id="user-1",
    session_id="session-1",
    rewind_before_invocation_id="execution-3",
)

한 번의 ADK 호출은 한 번의 OE 실행이므로 되감기는 전체 턴만 대상으로 합니다. 호출은 활성 지속형 형 호출 내에서 실행 되어야 하며, session_id는 해당 호출의 세션에 이름을 지정해야 합니다. SDK는 OE의 기존 실행 콜백 경로를 통해 현재 실행 ID 전송합니다. OE는 해당 실행을 로드하여 조직, 프로젝트, 작업 공간 및 세션을 파생합니다. 클라이언트 해당 좌표를 보내거나 자격 증명 시도하지 않습니다. 실행 ID 스트림 , 도구 결과 및 실행기 콜백에 대해 갖는 것과 동일한 역할 가집니다. 즉, 이미 워크로드-OE 콜백 신뢰 경계 내에 있는 요청 라우팅하며 공개 관리 자격 증명이 아닙니다. 한 트랜잭션 에서 OE는 실행에 여전히 활성 지속형 형 임대가 있는지 확인하고, 동일한 세션에서 제외할 첫 번째 실행을 해결하며, 이전 턴의 종료 상태 새로운 휴면 세션으로 복사합니다. 앤세스터 세션에서 턴을 되돌리려면 해당 앤세스터 세션을 호출하고 포크를 직접 요청 . 하위 세션은 조상 기록을 수정할 수 있는 권한을 상속하지 않습니다. 응답에는 새로운 session_id 및 보류 중인 execution_id가 포함됩니다. 해당 세션에 대한 다음 일반 호출은 대체 사용자 요청 으로 보류 중인 실행을 요청합니다.

이는 의도적으로 ADK의 반환 계약을 확장합니다. 네이티브 ADK는 지정된 세션을 변경하고 None을 반환합니다. Atlas Agent Engine은 해당 세션을 변경 불가 상태로 유지하고 SessionForkResponse을 반환하여 호출자가 새로운 session_id 및 execution_id를 계속 사용할 수 있도록 합니다. 메서드 이름과 인수는 ADK의 문서화된 인터페이스로 남아 있지만, app.runner는 올바른 반환 주석이 있는 Atlas Agent Engine 소유 유형입니다. Google의 Runner는 비공개의 시도 범위 실행 세부 정보로 유지됩니다. 일반 회전은 여전히 플랫폼 호출 인터페이스를 통해 시작됩니다. 퍼블릭 러너는 대체 실행 경로를 생성하지 않습니다.

어댑터는 ADK 이벤트를 스캔하거나, 실행 카탈로그를 유지하거나, 단계 서수를 계산하거나, 스냅샷 바이트를 제출 , 분기 키를 선택하지 않습니다. 첫 번째 턴 전에 되감거나, 이벤트 ID에 이름을 지정하거나, 다른 세션이 소유한 턴을 대상으로 지정하면 실패합니다. 활성 지속형 형 호출 외부에서 rewind_async()를 호출하는 것도 실패합니다. 즉, 순서가 맞지 않는 관리 되감기는 지원되지 않습니다. 각 재시도는 새로운 분기 요청 입니다. 클라이언트 멱등 키가 없습니다.

빠른 시작

pip install agent-engine-sdk-adk

uv add agent-engine-sdk-adk

개발

uv sync --extra dev

./scripts/test.sh agent-engine-sdk-adk