전체 글

Temporal을 활용해 Durable AI Workflow 구현하기

투자 리서치 에이전트에 Temporal을 붙였습니다. 완료된 모델·검색 결과를 재사용하는 방식과 외부 Tool을 Activity로 연결하며 번거로웠던 부분을 정리했습니다.

  • Temporal
  • OpenAI Agents SDK
  • AI Agent

투자 정보를 조사하는 에이전트를 OpenAI Agents SDK로 만들었습니다. Agent에 instructions와 tools를 넣고 Runner.run()을 호출하면 모델 호출, Tool 실행, Handoff가 이어집니다.

result = await Runner.run(
    starting_agent=orchestrator,
    input="OpenAI의 투자 정보를 조사해 주세요.",
)

return result.final_output

그런데 검색을 여러 번 하는 도중 Worker가 종료되면 어디서 다시 시작해야 할까요? 예를 들어 아래 순서에서 마지막에 실패할 수 있습니다.

모델 호출 1 완료
→ 검색 API 호출 완료
→ 모델 호출 2 완료
→ 문서 3개 수집 완료
→ 모델 호출 3 완료
→ 최종 결과를 저장하기 직전에 Worker 종료

처음부터 실행하면 앞에서 끝난 모델 호출과 검색도 반복합니다. 요금과 대기 시간이 다시 들고, 결과도 이전과 달라질 수 있습니다. 완료된 호출 결과를 남겨두고 이어서 실행하려고 Temporal을 붙였습니다.

구현할 때 참고한 공식 Cookbook과 예제 코드는 아래에 있습니다.

Temporal DocsDurable agent with tools using the OpenAI Agents SDKOpenAIAgentsPlugin과 activity_as_tool을 이용해 모델 호출과 Tool 실행을 durable하게 만드는 공식 Python Cookbook입니다.docs.temporal.io

GitHubjaeyoung0509/temporal-examples · react-agents이 글에서 살펴보는 투자 리서치 Agent의 Workflow, Activity, FastAPI, 테스트 전체 코드입니다.github.com

이 글에서 OpenAI가 의미하는 것

예제는 OpenAI Agents SDK의 Agent, Handoff, Runner, tracing 인터페이스를 사용합니다. 실제 모델 호출은 OpenAI 호환 API를 통해 Gemini로 보냅니다. Agents SDK를 사용하지만 모델 제공자는 Gemini인 구성입니다.

모델 호출과 검색 결과를 남기기

이 예제에서는 여러 Agent가 역할을 나누고 검색 Tool을 반복해서 호출합니다. OpenAI Agents SDK의 Agent, Handoff, Guardrail, Session으로 이런 흐름을 구성할 수 있습니다. OpenAI 공식 문서에 따르면 SDK는 Agent loop, multi-agent Handoff, resumable run state, guardrail과 tracing을 제공합니다.

실행 중인 Python 프로세스가 종료됐을 때의 복구는 별도로 구성해야 합니다. Temporal 통합은 모델과 Tool 호출의 결과를 Event History에 남깁니다. Worker가 중단되면 그 기록을 replay해 완료된 결과를 재사용합니다.

2025년 처음 발표된 Temporal의 OpenAI Agents SDK 통합은 2026년 3월 23일 기준 GA가 되었습니다. 발표 당시 설명과 현재 상태는 Temporal 공식 발표 글에서 함께 확인할 수 있습니다.

AI Engineer World

이번 예제: 투자 정보를 조사하는 ReAct Agent

예제는 회사 이름, 웹사이트, 국가 같은 정보를 받아 투자 내역을 조사합니다. Orchestrator가 회사 식별이 충분한지 판단하고, 모호하면 Clarifier로, 충분하면 Researcher로 Handoff합니다. Researcher는 Firecrawl 검색 Tool을 반복 호출한 뒤 출처가 포함된 InvestmentSnapshot을 반환합니다.

다이어그램을 불러오는 중입니다.

코드의 책임은 다음처럼 나뉩니다.

컴포넌트책임
FastAPIWorkflow를 시작하고 workflow_id 반환, 상태 조회
Temporal Workflow실행 상태와 분기, 복구 가능한 orchestration
OpenAI Agents SDKAgent loop, Tool 선택, Handoff, structured output
Firecrawl Activity검색과 문서 수집이라는 비결정적 I/O
Pydantic modelsAPI, Workflow, Tool, 모델 출력 사이의 계약

모델 호출과 외부 검색을 Activity로 실행해 완료 결과를 기록합니다. Workflow는 그 결과를 받아 다음 Agent와 상태를 결정합니다.

모델, 검색, 출력 타입을 연결한 코드

1. Runner.run()은 그대로 Workflow 안에 둡니다

Workflow 코드는 예상보다 작습니다.

@workflow.defn
class InvestmentResearchWorkflow:
    @workflow.run
    async def run(self, input: ResearchWorkflowInput) -> ResearchJobState:
        self._set_state(ResearchStatus.RUNNING, ResearchStage.ORCHESTRATING)

        result = await Runner.run(
            build_orchestrator_agent(input.model),
            input=_research_prompt(input),
        )

        outcome = result.final_output_as(
            ResearchOutcome,
            raise_if_incorrect_type=True,
        ).root
        # clarification 또는 completed 상태 저장

기존 Agents SDK의 프로그래밍 모델을 버리고 별도의 그래프 DSL로 다시 작성하지 않습니다. OpenAIAgentsPlugin이 Agents SDK의 모델 호출을 Temporal Activity로 실행하도록 연결합니다.

def openai_agents_plugin() -> OpenAIAgentsPlugin:
    return OpenAIAgentsPlugin(
        model_params=ModelActivityParameters(
            start_to_close_timeout=timedelta(minutes=2),
        )
    )

같은 plugin 설정을 API의 Temporal Client와 Worker 양쪽에 등록합니다. 모델 호출이 Activity 경계를 가지므로 완료된 응답은 Workflow History와 연결되고, Workflow replay 중에는 모델을 무조건 다시 호출하는 대신 기록된 완료 결과를 사용합니다.

2. 외부 검색은 activity_as_tool로 감쌉니다

Research Agent가 사용하는 Firecrawl은 네트워크 I/O이고 요금과 rate limit이 있는 외부 서비스입니다. 따라서 일반 @function_tool이 아니라 Temporal Activity로 정의한 뒤 Agent Tool로 노출합니다.

def _search_tool() -> Tool:
    return activity_as_tool(
        firecrawl_search_activity,
        start_to_close_timeout=timedelta(minutes=3),
        summary=(
            "Search the web with Firecrawl and return "
            "source-backed markdown documents."
        ),
    )
@activity.defn(name="firecrawl_search")
def firecrawl_search(request: FirecrawlSearchRequest) -> FirecrawlSearchResult:
    pages = client.search(
        request.query,
        limit=request.limit,
        scrape_limit=request.scrape_limit,
    )
    return build_firecrawl_search_result(
        request,
        pages,
        retrieved_at=datetime.now(UTC),
    )

datetime.now()와 HTTP 호출은 replay되어야 하는 Workflow 안이 아니라 Activity 안에 있습니다. 반대로 Workflow에서 필요한 시간은 workflow.now()를 사용합니다. Workflow는 replay할 때 같은 Command 순서를 만들어야 하므로, 외부 상태에 따라 값이 달라지는 작업을 Activity에 둡니다.

3. 완료와 추가 질문의 출력 타입을 나눕니다

모델 출력은 completed와 needs_clarification의 discriminated union입니다.

ResearchOutcomeValue = Annotated[
    CompletedResearchOutcome | ClarificationResearchOutcome,
    Field(discriminator="status"),
]

class ResearchOutcome(RootModel[ResearchOutcomeValue]):
    pass

Firecrawl 역시 FirecrawlSearchRequest와 FirecrawlSearchResult를 사용합니다. Pydantic으로 출력 구조와 다음 단계에 전달할 값을 검사합니다. 조사 내용이 사실인지 확인하는 일은 별도로 필요합니다.

실제로 실패하면 어디서 재개될까요?

복구할 때는 Workflow History에 완료 결과가 기록됐는지를 봅니다. Activity 내부의 Python 코드가 중간 줄부터 이어서 실행되는 것은 아닙니다.

실패 시점이 예제에서 일어나는 일
Firecrawl Activity가 완료된 뒤 Worker 종료완료 결과를 History에서 읽으므로 같은 Tool 호출을 다시 실행하지 않고 다음 Agent turn을 이어감
Firecrawl Activity 실행 도중 Worker 종료완료 기록이 없으므로 Activity가 다시 시도될 수 있음. 현재 Activity가 검색과 scrape를 함께 하므로 둘 다 재실행될 수 있음
모델 Activity 완료 뒤 Workflow Worker 종료저장된 모델 결과를 replay하고 다음 분기부터 계속 진행
모델 호출 도중 timeout 또는 rate limitActivity retry 정책의 범위에서 모델 호출을 다시 시도. 실패한 요청의 과금 여부는 모델 제공자 정책에 따름
최종 결과의 schema 검증이 계속 실패검증이 실패한 위치와 예외 처리에 따라 실행이 실패하거나 호출이 반복될 수 있음. 재시도 상한과 실패 처리를 확인해야 함

완료가 기록된 모델·Tool 결과는 재사용합니다. 완료 기록이 없는 Activity는 재시도 정책에 따라 다시 실행될 수 있습니다.

이 차이를 알고 Activity 크기를 정해야 합니다. Firecrawl 검색과 각 문서 scrape를 서로 다른 비용·복구 단위로 운영하고 싶다면 현재 하나인 Activity를 더 나눌 수 있습니다. 반대로 너무 잘게 나누면 History와 운영 복잡성이 커집니다. 같이 재시도해도 되는 작업인지, 다시 실행할 때 비용이 얼마나 드는지를 보고 Activity의 범위를 정해야 합니다.

Workflow ID로 상태 조회하기

API는 리서치가 끝날 때까지 HTTP 연결을 붙잡지 않습니다. Workflow를 시작하고 202 Accepted와 ID를 반환합니다.

workflow_id = f"investment-research-{uuid4()}"

await temporal_client.start_workflow(
    InvestmentResearchWorkflow.run,
    workflow_input,
    id=workflow_id,
    task_queue=settings.temporal_task_queue,
)

return ResearchJobResponse(
    workflow_id=workflow_id,
    status=ResearchStatus.QUEUED,
)

클라이언트는 ID로 상태를 조회합니다. Workflow의 local state는 Query로 외부에 노출됩니다.

@workflow.query
def get_state(self) -> ResearchJobState:
    return self._state

클라이언트는 workflow_id로 진행 상태를 조회합니다. 여러 Worker가 같은 Task Queue를 처리할 수 있고, Worker가 종료돼도 Temporal Service에는 실행 기록이 남습니다.

동시 실행 수를 늘릴 때는 별도 용량 계획이 필요합니다. Worker 수, Task Queue backlog, provider rate limit, Temporal Namespace 용량, payload 크기와 비용 예산을 함께 설계해야 합니다. multi-tenant 환경이라면 큰 고객의 작업이 Queue를 독점하지 않도록 Task Queue Fairness 같은 운영 정책도 검토해야 합니다.

통합하면서 실제로 아쉬웠던 점

Temporal과 OpenAI Agents SDK의 결합은 생각보다 자연스럽습니다. OpenAIAgentsPlugin을 등록하면 기존 Runner.run() 중심의 코드를 크게 바꾸지 않고 모델 호출을 durable boundary로 옮길 수 있습니다. 다만 OpenAI가 호스팅하지 않는 외부 Tool을 사용할 때는 Activity 경계를 직접 만들어야 한다는 점은 아직 번거롭게 느껴졌습니다.

예를 들어 OpenAI 모델과 Agents SDK의 hosted Web Search를 사용한다면 Agent 정의에 Tool을 바로 추가할 수 있습니다.

from agents import Agent, WebSearchTool

researcher = Agent(
    name="Investment Researcher",
    instructions="Find source-backed investment information.",
    tools=[WebSearchTool()],
)

Web Search의 구현과 실행은 OpenAI가 관리하므로 애플리케이션에서 검색 함수를 따로 만들거나 그 검색 Tool만을 위한 Temporal Activity를 Worker에 등록하지 않아도 됩니다. Temporal plugin이 감싸는 모델 호출 안에서 hosted Tool을 사용하게 됩니다.

반면 이 예제는 모델 제공자로 Gemini를 사용하고 검색에는 Firecrawl을 선택했습니다. Firecrawl은 Agents SDK의 hosted Tool이 아니라 애플리케이션이 직접 호출하는 외부 서비스입니다. 그래서 다음 경계를 모두 코드로 정의해야 했습니다.

# 1. 외부 I/O를 Activity로 구현
@activity.defn(name="firecrawl_search")
def firecrawl_search(
    request: FirecrawlSearchRequest,
) -> FirecrawlSearchResult:
    ...

# 2. Activity를 Agent Tool로 변환
search_tool = activity_as_tool(
    firecrawl_search_activity,
    start_to_close_timeout=timedelta(minutes=3),
)

# 3. Worker에도 Activity 등록
Worker(
    ...,
    activities=[firecrawl_search],
)

이 구분에는 이유가 있습니다. Temporal은 Firecrawl 호출의 적절한 timeout, retry 가능한 오류, 직렬화할 입출력, 멱등성 조건을 자동으로 알 수 없습니다. 외부 I/O를 Activity로 드러내야 호출의 완료 여부를 History에 남기고 독립적으로 재시도할 수 있습니다. 이 설정은 외부 Tool마다 직접 정해야 합니다.

작성해야 하는 코드를 비교하면 차이가 있습니다.

OpenAI hosted Web Search
Agent에 Tool 추가
→ 별도 검색 구현과 Activity 등록 없음

Firecrawl 같은 외부 Tool
Activity 구현
→ activity_as_tool 변환
→ Worker 등록
→ timeout·retry·입출력 계약 관리

Firecrawl을 붙이면서 Activity 구현, Tool 변환, Worker 등록을 각각 작성해야 했습니다. 외부 Tool이 늘면 이 코드도 반복됩니다. timeout과 retry는 명시하되, Tool 변환과 Worker 등록은 공통 helper로 묶을 수 있겠다고 느꼈습니다.

이 예제에서 의도적으로 다루지 않은 것들

예제에서는 모델 호출과 검색을 Activity로 연결했습니다. 실제 서비스에 넣기 전에는 아래 항목도 구현하거나 확인해야 합니다.

고려사항프로덕션에서 확인할 내용
요청 멱등성클라이언트의 idempotency key나 비즈니스 request ID를 Workflow ID로 사용하고 중복 시작 정책을 정해야 합니다.
Side effect 멱등성결제, 이메일 발송, 티켓 생성은 외부 시스템의 idempotency key, deduplication, reconciliation이 필요합니다.
비용 상한max_turns, 검색·출처 수, token·cost budget을 두고 상한 도달 시 축약, 승인 요청, 실패 중 어떤 정책을 적용할지 정해야 합니다.
History와 payload큰 검색 원문은 object storage에 두고 Workflow에는 key, hash, excerpt를 남겨야 합니다. 긴 실행에는 context trimming과 Continue-As-New도 검토해야 합니다.
Human-in-the-loop현재 Clarifier는 needs_clarification으로 종료합니다. 같은 실행을 이어가려면 Update나 Signal을 기다리는 흐름이 필요합니다.
사실 검증Pydantic은 데이터 형태를 검증할 뿐입니다. 출처와 주장 간 검증, 신뢰 도메인 정책, 충돌 처리, eval dataset은 별도 설계가 필요합니다.
관찰 가능성과 보안Temporal Web UI와 Agent trace를 함께 연결하고, History와 trace에 남는 prompt·원문·출력의 암호화, 보존 기간, redaction, 접근 제어를 정해야 합니다.

현재 예제만으로 비용 상한, 요청 중복 방지, 출처 검증까지 갖춘 것은 아닙니다.

다음 실습에서 확인할 것

아래 장애 실험은 아직 측정 결과를 정리하지 못했습니다. 완료 기록의 재사용과 실행 중 재시도를 나눠 확인하려고 합니다.

  1. Firecrawl 완료 직후 Worker를 강제 종료하고, 재시작 뒤 검색 호출 횟수가 늘지 않는지 확인합니다.
  2. Firecrawl 실행 도중 Worker를 종료해 Activity 전체가 다시 실행되는지 확인합니다.
  3. 모델 호출에 일시 오류와 영구 오류를 주입하고 retry 간격, 최대 시도, 최종 상태를 기록합니다.
  4. 같은 리서치를 OpenAI hosted Web Search로도 구현해 Firecrawl Activity 방식과 코드, History, trace를 비교합니다.
  5. Agent가 의도적으로 너무 많이 검색하게 만들고 max_turns와 비용 budget을 추가합니다.
  6. Clarifier 결과에서 Workflow를 끝내지 않고 Update로 사용자 답변을 받아 같은 실행을 이어갑니다.
  7. 큰 검색 원문을 object storage로 옮긴 뒤 History 크기를 전후 비교합니다.
  8. 같은 idempotency key로 POST를 두 번 보내도 Workflow가 하나만 생기는지 검증합니다.

실험할 때는 모델·Tool 호출 횟수와 복구 시간, 중복 과금을 기록할 예정입니다. 아직 수치가 없으므로 이 글에서 복구 성능이나 비용 절감 폭을 단정하지는 않습니다.

붙여보고 남은 점

OpenAIAgentsPlugin을 등록하면 Runner.run()을 Workflow 안에서 사용하고, 완료된 모델 결과를 History에서 재사용할 수 있습니다. 외부 검색도 activity_as_tool로 연결했습니다.

가장 번거로웠던 부분은 외부 Tool마다 Activity 구현과 Worker 등록을 반복하는 일이었습니다. 다음에는 이 코드를 묶어보고, Worker를 종료하는 시점에 따라 모델과 검색이 몇 번 실행되는지 확인해보려고 합니다.

참고 자료