Kitaru와 함께하는 지속 실행

Kitaru와 함께하는 지속 실행 (Durable Execution with Kitaru)

Kitaru는 AI 에이전트를 위한 지속 실행 계층이에요. Pydantic AI 어댑터는 pydantic_ai.durable_exec가 아니라 kitaru 패키지가 kitaru.adapters.pydantic_ai를 통해 제공합니다. Kitaru의 flow·checkpoint 개념과 함께 에이전트를 지속으로 만드는 방법을 살펴볼게요.

출처: 문서

본문

지속 실행 (Durable Execution)

Kitaru는 에이전트 진행을 flows와 checkpoints로 기록해요. flow는 나중에 재개할 수 있는 지속 런이고, checkpoint는 나중에 회복 중 재사용할 수 있는 완료된 모델 요청, 도구 호출, MCP 호출, 또는 사람 대기입니다.

예를 들어 에이전트가 모델을 호출해 유용한 응답을 받고, 도구 호출을 시작한 뒤 프로세스가 크래시했다고 해 봐요. 지속 실행이 없으면 프로그램을 재시작할 때 보통 모델 요청을 반복하고 이후의 사이드 이펙트도 반복할 수 있어요. Kitaru에서는 재시작된 flow가 런을 재생하고, 모델 요청에 완료된 checkpoint를 재사용하며, 첫 미완료 지점부터 계속합니다.

이것은 장기 실행 에이전트, 사람 개입 워크플로, 그리고 반복되는 모델 요청이나 외부 API 호출이 비용·시간이 들거나 사이드 이펙트를 중복하게 만드는 애플리케이션에 유용합니다.

KitaruAgent를 호출하면 여러분의 애플리케이션은 여전히 기저의 Pydantic AI 에이전트를 호출해요. Kitaru는 그 호출에 대해 flow를 시작하거나 재개합니다. 기본 "calls" checkpoint 전략으로는 완료된 모델 요청, 도구 호출, MCP 호출, 사람 대기를 Kitaru의 checkpoint 스토리지에 기록합니다. 회복 시 Kitaru는 파이썬 함수를 이미 checkpoint가 있는 연산에 도달할 때까지 다시 실행하고, 그 연산의 저장된 결과를 반환한 뒤 완료되지 않은 첫 연산부터 계속합니다.

지속 에이전트 (Durable Agent)

kitaru.adapters.pydantic_ai의 KitaruAgent로 일반 Agent를 감싸 지속으로 만들 수 있어요. Kitaru를 Pydantic AI와 별도로 설치합니다:

uv add "kitaru[pydantic-ai]"

Kitaru 로컬 서버로 로컬 개발하려면 local 엑스트라도 설치하세요:

uv add "kitaru[pydantic-ai,local]"

예제를 실행하기 전에 프로젝트를 초기화하고 연결을 확인하세요:

kitaru init
kitaru login
kitaru status

다음은 Kitaru를 쓰는 가장 작은 지속 Pydantic AI 에이전트입니다:

from pydantic_ai import Agent
from kitaru.adapters.pydantic_ai import KitaruAgent

agent = Agent('openai:gpt-5-nano', name='researcher')
durable_agent = KitaruAgent(agent)

result = durable_agent.run_sync('Summarize quantum error correction.')
print(result.output)

KitaruAgent는 원래 에이전트 객체를 대체하지 않아요. 기본 호출 수준 checkpoint 전략으로, 실제 Pydantic AI 런을 위해 그 에이전트에 위임하고 런이 실행되는 동안 회복 가능한 연산을 기록합니다:

모델 요청;
Pydantic AI 도구 호출;
MCP 도구 호출;
@hitl_tool 사람 대기.

Agent.run과 Agent.run_sync를 포함한 일반 런 메서드를 노출합니다. 원래 Agent는 Kitaru 밖에서 평소처럼 사용할 수 있어요.

프로덕션 Flows (Production Flows)

주의

위의 최소 래퍼는 로컬 개발용인 Kitaru의 자동 flow 생성을 사용합니다. 원격 스택이나 프로덕션 서비스에서는 지속 에이전트 호출을 명시적인 @kitaru.flow 안에 넣어서 Kitaru가 제출·재생·검사할 안정적인 flow 진입점을 갖게 하세요.

import kitaru
from pydantic_ai import Agent
from kitaru.adapters.pydantic_ai import KitaruAgent

agent = Agent('openai:gpt-5-nano', name='researcher')
durable_agent = KitaruAgent(agent)


@kitaru.flow
def research_topic(topic: str) -> str:
    result = durable_agent.run_sync(f'Summarize {topic}.')
    return result.output

첫 실험에는 짧은 래퍼를 쓰고, 런이 로컬 프로세스를 넘어서야 한다면 명시적 flow를 사용하세요.

Checkpoint 전략 (Checkpoint Strategy)

KitaruAgent는 두 가지 checkpoint 전략을 지원합니다:

"calls" (기본값) — 재생 안전한 모델 요청, 도구 호출, MCP 호출, 사람 대기를 별도의 checkpoint로 영속화합니다. 개별 호출이 비싸거나 사이드 이펙트가 있는 대부분의 에이전트에 적합합니다.
"turn" — 하나의 checkpoint가 전체 에이전트 런을 감쌉니다. 호출별 checkpoint가 불필요한 단순한 런이나, 스트리밍 제약 때문에 전체 턴 checkpoint가 필요한 경우에 적합합니다.

기본 "calls" 전략에서 Kitaru는 사용자 정의 @kitaru.checkpoint 본문 안에 중첩 checkpoint를 만들 수 없어요. durable_agent.run_sync(...)가 사용자 @kitaru.checkpoint 안에서 실행되면, Kitaru는 별도의 모델·도구·MCP checkpoint 행을 만드는 대신 그 외부 checkpoint 아래에 전체 에이전트 턴을 기록합니다.

고급 checkpoint 설정은 Kitaru Pydantic AI adapter guide를 보세요.

사람 개입 (Human-in-the-loop)

순수한 사람 승인·데이터 입력 게이트에는 Kitaru의 @hitl_tool을 선호하세요. 대기를 지속 도구 호출로 바꿔서: 프로세스가 사람 응답을 기다리는 동안 멈출 수 있고, 응답이 제공되면 회복이 계속될 수 있어요.

from kitaru.adapters.pydantic_ai import hitl_tool


@hitl_tool(question='Approve publishing this answer?', schema=bool)
def approve_publish(summary: str) -> bool: ...

일반 도구 본문 대기도 사람 입력을 기다릴 수 있지만, sync 도구 본문 대기는 추가 Kitaru 설정이 필요해요. 그 패턴이 필요하면 Kitaru Pydantic AI adapter guide의 사람 개입 섹션을 따르세요.

Pydantic AI 자체의 지연 도구 패턴은 deferred tools를 보세요.

스트리밍 (Streaming)

Kitaru는 몇 가지 제약과 함께 Pydantic AI 스트리밍을 지원해요. 이벤트 스트리밍에는 Agent.run의 event_stream_handler 인수를 선호합니다. 런이 event_stream_handler를 쓰면 Kitaru는 그 호출에 대해 턴 checkpoint로 폴백합니다.

run_stream()이나 iter()를 쓰면 스트리밍 호출을 명시적인 @kitaru.checkpoint로 감싸세요. 그러면 Kitaru가 각 스트리밍 이벤트를 별도로 영속화하는 대신 재생할 지속 연산 하나를 얻습니다.

요구사항과 제약 (Requirements and Constraints)

Kitaru를 Pydantic AI와 함께 쓸 때:

에이전트를 생성 시점에 구체적인 모델로 정의하세요. 예: Agent('openai:gpt-5-nano', ...).
각 지속 에이전트에 안정적인 name을 주세요. Kitaru는 런 간에 영속된 작업을 식별하는 데 사용해요.
KitaruAgent를 쓸 때는 model=로 런마다 모델을 덮어쓰지 마세요.
원격 스택과 프로덕션 서비스에는 명시적인 @kitaru.flow를 사용하세요. 자동 flow 생성은 로컬 전용이에요.
사용자 정의 @kitaru.checkpoint 본문 안에 중첩 Kitaru checkpoint를 피하세요.

Kitaru와 함께하는 지속 실행