AG-UI Middleware

• AG-UI Middleware는 AbstractAgent 실행과 이벤트 소비자 사이에 끼어들어 이벤트 스트림을 가공하는 계층
• agent.runAgent() 호출 시 등록된 미들웨어 체인을 통과하는 RxJS Observable 기반 파이프라인
• 핵심 책임은 이벤트 변환·필터링·메타데이터 주입·에러 처리·모니터링의 5가지 횡단 관심사(cross-cutting concerns)
• agent 본체 코드를 수정하지 않고 기능을 확장하는 양파(onion) 구조의 데코레이터 패턴

해당 개념이 필요한 이유

• agent의 핵심 로직과 부가 기능(로깅, 인증, 필터링)을 분리해 단일 책임 원칙 유지
• 동일한 에이전트를 다양한 환경(개발/운영, 디버그/프로덕션)에서 재사용 가능
• 이벤트 스트림에 일률적으로 적용되는 정책(예: 욕설 필터)을 선언적으로 조합
• 인증·권한·rate limit 같은 정책을 agent 외부에서 강제해 보안 경계 명확화

AS-IS

미들웨어 없이 agent 안에 모든 부가 기능이 섞인 구조:

class MyAgent extends AbstractAgent {
  run(input: RunAgentInput): Observable<BaseEvent> {
    console.log("[REQ] start")                     // 로깅
    if (!input.forwardedProps?.token) throw Error  // 인증
    return this.callBackend(input).pipe(
      filter(e => !this.isDangerous(e)),           // 도구 필터
      map(e => this.maskProfanity(e)),             // 욕설 마스킹
      tap(e => this.recordMetric(e)),              // 메트릭
      finalize(() => console.log("[DONE]"))        // 종료 로그
    )
  }
}

TO-BE

미들웨어로 관심사를 분리한 구조:

flowchart LR
    UI[UI: runAgent input] --> A[authMiddleware]
    A --> P[profanityMiddleware]
    P --> L[loggingMiddleware]
    L --> F[filterToolCallsMiddleware]
    F --> AG[agent.run]
    AG -. event .-> F
    F -. event .-> L
    L -. event .-> P
    P -. event .-> A
    A -. event .-> UI

agent.use(authMiddleware, profanityMiddleware, loggingMiddleware, filterToolCallsMiddleware)
await agent.runAgent(input)

Middleware의 두 페이즈

Middleware는 시점이 다른 두 흐름을 동시에 다룬다.

페이즈	시점	횟수	RxJS 관점
Phase 1: 입력	사용자가 메시지 보낼 때	1회	subscribe() 시점 동기 함수 호출
Phase 2: 이벤트	AI 응답이 흘러나올 때	N회	비동기 emit per event

한 미들웨어 코드 안에서 두 페이즈 영역이 명확히 구분된다:

const myMiddleware: MiddlewareFunction = (input, next) => {
  // ── Phase 1 영역: 입력 가공 (1회 실행) ──
  const modifiedInput = { ...input, /* ... */ }
 
  return next.run(modifiedInput).pipe(
    // ── Phase 2 영역: 이벤트 가공 (event마다 실행) ──
    map(event => /* ... */),
    tap(event => /* ... */),
    finalize(() => /* 종료 시 1회 */)
  )
}

양파(Onion) 패턴 동작 모델

Phase 1 — 입력이 안쪽으로 흐름

sequenceDiagram
    autonumber
    participant UI
    participant Auth as authMiddleware
    participant Prof as profanityMiddleware
    participant Log as loggingMiddleware
    participant Filter as filterToolCallsMiddleware
    participant Agent as agent.run

    UI->>Auth: runAgent(input)
    Auth->>Auth: forwardedProps에 토큰 주입
    Auth->>Prof: next.run(authedInput)
    Prof->>Prof: messages 욕설 마스킹
    Prof->>Log: next.run(cleanedInput)
    Log->>Log: "[REQ] runId=..." 기록
    Log->>Filter: next.run(input)
    Filter->>Agent: next.run(input)
    Agent->>Agent: 백엔드로 SSE 요청

Phase 2 — 이벤트가 바깥쪽으로 흐름

sequenceDiagram
    autonumber
    participant UI
    participant Auth as authMiddleware
    participant Prof as profanityMiddleware
    participant Log as loggingMiddleware
    participant Filter as filterToolCallsMiddleware
    participant Agent as agent.run

    loop 매 이벤트마다
        Agent->>Filter: emit BaseEvent
        Filter->>Filter: 위험 도구면 DROP
        Filter->>Log: pass event
        Log->>Log: tap "[EVT] type"
        Log->>Prof: pass event
        Prof->>Prof: TEXT_MESSAGE_CONTENT 마스킹
        Prof->>Auth: pass event
        Auth->>UI: 최종 이벤트 전달
    end

핵심 비대칭은 입력은 1번, 이벤트는 매 emit마다 체인을 통과한다는 점이다. 그래서 pipe(...) 안의 map/tap은 이벤트 개수만큼 실행된다.

이벤트는 청크 단위로 흐른다

Phase 2가 “이벤트마다 N번 호출된다”고 했을 때, 그 N의 정체를 정확히 이해해야 미들웨어 로직을 올바르게 작성할 수 있다. AG-UI의 텍스트 메시지와 도구 호출은 둘 다 청크 단위로 분할되어 흘러나오기 때문이다(AG-UI Event 참고).

텍스트 메시지의 청크 구조

AI가 “안녕하세요 반갑습니다”를 스트리밍할 때 백엔드는 다음과 같이 분리된 이벤트들을 순차 emit한다:

TEXT_MESSAGE_START         (messageId)
TEXT_MESSAGE_CONTENT       (delta="안녕")
TEXT_MESSAGE_CONTENT       (delta="하세요")
TEXT_MESSAGE_CONTENT       (delta=" 반갑")
TEXT_MESSAGE_CONTENT       (delta="습니다")
TEXT_MESSAGE_END           (messageId)

이 6개 이벤트 각각이 미들웨어 체인을 통과한다. 따라서 profanityMiddleware의 pipe(map(...))은 6번 호출되며, delta가 든 4번에서만 마스킹 로직이 실제로 동작한다.

AG-UI는 동일한 정보를 더 컴팩트하게 표현하는 TEXT_MESSAGE_CHUNK 형태도 지원한다. 한 이벤트에 messageId+delta가 묶여 들어오고 별도 START/END가 없는 형태다. 미들웨어는 양쪽 형태를 모두 처리하도록 작성하는 게 안전하다.

도구 호출도 마찬가지

TOOL_CALL_START   (toolCallId, toolCallName="search")
TOOL_CALL_ARGS    (delta='{"query":')
TOOL_CALL_ARGS    (delta='"AG-UI"}')
TOOL_CALL_END     (toolCallId)

도구 인자(JSON 문자열)도 청크 단위로 emit되므로 한 호출당 ARGS 이벤트가 여러 번 발생한다. 미들웨어는 “완성된 인자 객체”를 한 번에 받는 게 아니라 JSON 조각을 누적해야 하는 상황을 항상 전제해야 한다.

작성 방식 두 가지

Function-Based — 단순 변환용

const prefixMiddleware: MiddlewareFunction = (input, next) => {
  return next.run(input).pipe(
    map(event => {
      if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
        return { ...event, delta: `[AI]: ${event.delta}` }
      }
      return event
    })
  )
}

시그니처: (input: RunAgentInput, next: AbstractAgent) => Observable<BaseEvent>

Class-Based — 상태/설정 필요 시

class MetricsMiddleware extends Middleware {
  private eventCount = 0
 
  constructor(private metricsService: MetricsService) { super() }
 
  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    const start = Date.now()
    return this.runNext(input, next).pipe(
      tap(event => {
        this.eventCount++
        this.metricsService.recordEvent(event.type)
      }),
      finalize(() => {
        this.metricsService.recordDuration(Date.now() - start)
      })
    )
  }
}

청크를 의미 단위로 받기 — runNext와 runNextWithState

청크 분할의 존재를 알면 자연스럽게 의문이 생긴다. “매번 청크를 직접 누적해야 하나?” 클래스 미들웨어가 제공하는 두 헬퍼가 이 부분을 도와준다. 단, 헬퍼의 의미를 정확히 알아야 오해가 없다.

runNext() — 합치기가 아니라 “정규화”

runNext()의 역할은 청크들을 하나의 이벤트로 합쳐주는 것이 아니라, 어떤 형태로 들어오든 일관된 분리형(START/CONTENT/END)으로 변환해주는 것이다.

[입력 — CHUNK 형태로 들어왔다고 가정]
TEXT_MESSAGE_CHUNK(delta="안녕")
TEXT_MESSAGE_CHUNK(delta="하세요")
TEXT_MESSAGE_CHUNK(delta=" 반갑")
TEXT_MESSAGE_CHUNK(delta="습니다")

[runNext() 통과 후 — 분리형으로 정규화]
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT(delta="안녕")
TEXT_MESSAGE_CONTENT(delta="하세요")
TEXT_MESSAGE_CONTENT(delta=" 반갑")
TEXT_MESSAGE_CONTENT(delta="습니다")
TEXT_MESSAGE_END

이벤트 개수는 그대로(또는 START/END가 추가되어 더 많아짐)이며, 미들웨어 pipe는 여전히 N번 호출된다. runNext가 보장하는 건 **“두 가지 입력 형태를 한 가지로 통일해 분기 처리를 줄여주는 것”**이지 청크 통합이 아니다.

완성된 메시지 한 덩어리를 받는 두 가지 패턴

청크가 아니라 완성된 텍스트 한 덩어리를 다루고 싶다면 두 가지 방법이 있다.

방법 A — TEXT_MESSAGE_END 시점에 직접 누적

class FullMessageMiddleware extends Middleware {
  private buffer = ""
 
  run(input, next) {
    return this.runNext(input, next).pipe(
      tap(event => {
        if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
          this.buffer += event.delta
        }
        if (event.type === EventType.TEXT_MESSAGE_END) {
          console.log("완성된 메시지:", this.buffer)
          this.buffer = ""
        }
      })
    )
  }
}

방법 B — runNextWithState()의 누적 messages 활용

class StateMiddleware extends Middleware {
  run(input, next) {
    return this.runNextWithState(input, next).pipe(
      tap(({ event, messages, state }) => {
        const lastMsg = messages[messages.length - 1]
        if (event.type === EventType.TEXT_MESSAGE_END) {
          console.log("완성된 메시지:", lastMsg.content)
        }
      })
    )
  }
}

runNextWithState()는 이벤트는 그대로 N번 emit하되, 각 시점에 **“지금까지 누적된 messages와 state”**를 함께 제공한다. 청크 누적 로직을 직접 짤 필요 없이 마지막 메시지를 읽기만 하면 된다.

세 단계 비교

헬퍼	이벤트 개수 변화	제공하는 것
next.run() (raw)	그대로	event만
runNext()	CHUNK → START/CONTENT/END로 형태 통일	event만, 형태 일관성
runNextWithState()	위와 동일	event + 누적 messages + 누적 state

요약하자면 “이벤트를 1개로 합쳐주는 헬퍼는 없다”. 합치고 싶다면 END 시점에 buffer를 비우거나 runNextWithState의 누적 messages를 읽어야 한다.

내장 Middleware — FilterToolCallsMiddleware

도구 호출 이벤트를 화이트리스트/블랙리스트로 필터링한다.

import { FilterToolCallsMiddleware } from "@ag-ui/client"
 
const allow = new FilterToolCallsMiddleware({
  allowedToolCalls: ["search", "calculate"]
})
 
const block = new FilterToolCallsMiddleware({
  disallowedToolCalls: ["delete", "modify"]
})
 
agent.use(allow)

이 미들웨어가 차단하는 건 이미 방출된 TOOL_CALL_* 이벤트다. 모델이나 백엔드 런타임에서 도구가 실제로 실행되는 것을 막는 게 아니다. 이 차이는 도구 실행 주체가 어디냐에 따라 결과가 크게 달라지므로 별도로 짚을 필요가 있다.

Backend vs Frontend 도구 — 차단의 비대칭

AG-UI에서 도구는 두 군데에서 실행될 수 있고, 차단되는 시점은 동일하게 Phase 2(이벤트 반환 흐름)지만 실행 시점이 달라 결과가 다르다.

Backend 도구 — 실행은 끝났고 표시만 가려진다

sequenceDiagram
    autonumber
    participant UI
    participant MW as filterToolCallsMiddleware
    participant Agent as 백엔드 agent
    participant Tool as bash 실행기

    UI->>MW: Phase 1: runAgent(input)
    MW->>Agent: input 통과
    Agent->>Tool: bash 실제 실행 (서버에서)
    Tool-->>Agent: 결과 반환
    Note over Agent,Tool: 실행은 이미 끝남
    Agent->>MW: Phase 2: TOOL_CALL_START(name='bash')
    MW->>MW: 차단 대상 → DROP
    Note over MW,UI: UI는 이 이벤트를 못 봄
    Agent->>MW: TEXT_MESSAGE_CONTENT(결과 요약)
    MW->>UI: 통과

도구 실행이 이벤트가 emit되기 전에 이미 백엔드에서 끝났다. 미들웨어가 보는 TOOL_CALL_*는 “실행됐다는 알림”일 뿐이므로 차단해도 실행에는 영향이 없고 UI 표시만 가려진다. 내부 헬퍼 도구나 디버그용 검색처럼 UI 노이즈를 줄이고 싶을 때 유용하다.

Frontend 도구 — 트리거 자체가 사라진다

Frontend 도구는 백엔드가 실행하지 않고, “UI야, 이 도구 좀 실행해줘”라는 요청 이벤트만 보낸다. UI가 그 이벤트를 받아서 직접 실행한다(예: confirm() 다이얼로그, DOM 조작, 로컬 파일 접근).

sequenceDiagram
    autonumber
    participant UI
    participant MW as filterToolCallsMiddleware
    participant Agent as 백엔드 agent
    participant FETool as UI 내부의<br/>tool executor

    UI->>MW: Phase 1: runAgent(input)
    MW->>Agent: input 통과
    Agent->>Agent: LLM이 'confirm()' 도구 호출 결정
    Note over Agent: 백엔드는 실행 안 함<br/>"UI에 위임" 모드
    Agent->>MW: Phase 2: TOOL_CALL_START(name='confirm')
    MW->>MW: 차단 대상 → DROP
    Note over MW,UI: UI는 이벤트를 못 봄
    Note over UI,FETool: 도구 실행 트리거 자체가<br/>오지 않음 → 실행 안 됨

도구 실행이 이벤트가 UI에 도착해야 비로소 트리거된다. 미들웨어가 그 이벤트를 차단하면 UI는 트리거를 받지 못하고, 실행 자체가 일어나지 않는다.

같은 차단, 다른 결과

케이스	도구 실행 시점	미들웨어가 차단하는 것	차단의 효과
Backend 도구	Phase 2 emit 전	TOOL_CALL_* 이벤트	UI 표시만 차단. 실행은 이미 끝남
Frontend 도구	Phase 2 emit을 트리거로 사용	TOOL_CALL_* 이벤트	트리거 자체가 차단 → 실행 안 됨

이 비대칭 때문에 FilterToolCallsMiddleware를 보안 통제로 쓰면 안 된다. 진짜 위험한 도구를 차단하려면:

• Backend 도구는 백엔드 권한 시스템에서 차단해야 한다. 미들웨어는 모델 호출과 실제 실행을 막을 수 없다.
• Frontend 도구는 미들웨어로 이벤트를 차단하면 실행은 막을 수 있으나, 모델은 여전히 호출 의도를 가지고 있다. 모델 측 가드도 함께 필요하다.

미들웨어 필터의 진짜 용도는 보안이 아니라 UI 노이즈 감소라고 정리할 수 있다.

실전 패턴 5가지

① Auth — Phase 1만 사용

const authMiddleware: MiddlewareFunction = (input, next) => {
  const token = localStorage.getItem("jwt")
  return next.run({
    ...input,
    forwardedProps: { ...input.forwardedProps, authorization: `Bearer ${token}` }
  })
}

② Tool Filter — Phase 2 차단

const dangerousTools = new Set(["deleteAccount", "transferFunds"])
 
const filterDangerousMiddleware: MiddlewareFunction = (input, next) => {
  let blockedId: string | null = null
  return next.run(input).pipe(
    filter(event => {
      if (event.type === EventType.TOOL_CALL_START && dangerousTools.has(event.toolCallName)) {
        blockedId = event.toolCallId
        return false
      }
      if ((event.type === EventType.TOOL_CALL_ARGS || event.type === EventType.TOOL_CALL_END)
          && event.toolCallId === blockedId) {
        return false
      }
      return true
    })
  )
}

③ Profanity Filter — Phase 2 변형

const profanityMiddleware: MiddlewareFunction = (input, next) => {
  return next.run(input).pipe(
    map(event => {
      if (event.type === EventType.TEXT_MESSAGE_CONTENT ||
          event.type === EventType.TEXT_MESSAGE_CHUNK) {
        return { ...event, delta: maskProfanity(event.delta) }
      }
      return event
    })
  )
}

④ Logging — 양쪽 페이즈

const loggingMiddleware: MiddlewareFunction = (input, next) => {
  console.log(`[REQ] runId=${input.runId} threadId=${input.threadId}`)
  const start = Date.now()
  return next.run(input).pipe(
    tap(event => console.log(`[EVT] ${event.type}`)),
    finalize(() => console.log(`[DONE] ${Date.now() - start}ms`))
  )
}

⑤ Rate Limit — Phase 1 지연

let lastRunAt = 0
const MIN_INTERVAL = 2000
 
const rateLimitMiddleware: MiddlewareFunction = (input, next) => {
  const wait = Math.max(0, lastRunAt + MIN_INTERVAL - Date.now())
  lastRunAt = Date.now() + wait
  return timer(wait).pipe(switchMap(() => next.run(input)))
}

등록 순서와 배치 전략

agent.use(authMiddleware, profanityMiddleware, loggingMiddleware, filterMiddleware)

페이즈	흐름 방향	순서
Phase 1 (입력)	바깥 → 안쪽	auth → profanity → logging → filter → agent
Phase 2 (이벤트)	안쪽 → 바깥	agent → filter → logging → profanity → auth → UI

배치 가이드:

• 인증/인가 → 가장 바깥 (요청 차단 시 안쪽 실행 안 됨)
• 로깅/메트릭 → 중간 (변형된 입력과 변형된 이벤트 모두 관찰)
• 이벤트 필터/변형 → 가장 안쪽 (agent에 가까운 raw 이벤트 직접 처리)

주의사항 및 함정

1. connectAgent()는 미들웨어를 거치지 않는다 — connect()를 직접 호출하므로 인증·필터 등이 우회된다. 미들웨어는 runAgent()에서만 적용된다.
2. FilterToolCallsMiddleware는 보안 통제가 아니다 — 이벤트만 가릴 뿐 실제 도구 실행은 막지 않는다. Frontend 도구의 경우 트리거가 차단되어 실행은 막히지만, 모델은 여전히 호출 의도를 가진다.
3. pipe 안 연산은 이벤트 개수만큼 실행된다 — 텍스트와 도구 인자가 청크로 분할되므로 무거운 동기 연산을 넣으면 스트림 전체가 느려진다.
4. 에러는 RxJS 오퍼레이터로 처리 — try/catch가 아닌 catchError로 감싸야 스트림이 통째로 죽지 않는다.
5. 상태를 가지는 미들웨어는 인스턴스 공유 주의 — 동일 인스턴스를 여러 agent에 등록하면 카운터·버퍼 등이 섞인다.

Best Practices

1. Single responsibility — 한 미들웨어 = 한 가지 일
2. Graceful error handling — catchError로 스트림 보호
3. Non-blocking — I/O는 switchMap + from(promise) 등 async 패턴
4. Side-effect 명시 — state 수정 시 문서화
5. 독립 테스트 — mock next agent로 단위 테스트
6. 성능 인지 — 모든 이벤트가 통과하므로 무거운 연산 금지

참고 문서

• AG-UI Middleware Concept
• JS Middleware Reference