Managed Deep Agents에 커스텀 미들웨어 추가하기

Managed Deep Agents에 커스텀 미들웨어 추가하기

관리형 딥 에이전트에 내장 또는 커스텀 미들웨어를 추가할 수 있어요.

미들웨어는 모델 호출, 도구 호출, 에이전트 수명주기 주변에 동작을 추가합니다. 커스텀 도구와 마찬가지로 MDA는 미들웨어를 자동으로 발견하지 않습니다. 가져와서 에이전트 정의에 전달하세요.

Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 지역에서만 사용할 수 있어요.

커스텀 미들웨어를 middleware/ 아래에 넣고, 에이전트 진입점으로 가져와 에이전트 정의에 전달합니다:

my-agent/
  agent.ts
  middleware/
    audit.ts

전체 프로젝트 레이아웃은 프로젝트 구조를 참고하세요.

관리형 런타임은 여전히 backend, store, checkpointer, memory, skills, 시스템 프롬프트를 소유합니다. 미들웨어는 모델 호출, 도구 호출, 수명주기 훅 주변의 에이전트 동작에 집중해야 합니다.

출처: 문서

본문

미들웨어 추가하기 (Add middleware)

미들웨어를 사용해 PII를 마스킹하고, 호출 한도를 적용하고, 실패를 재시도하고, 모델 간 폴백하고, 모델을 동적으로 선택하거나, 도구 호출을 로깅하고 검사할 수 있습니다.

사전 구축 미들웨어 사용하기 (Use prebuilt middleware)

LangChain 사전 구축 미들웨어를 에이전트 정의에서 직접 사용할 수 있습니다:

import { defineDeepAgent } from "managed-deepagents";
import { modelCallLimitMiddleware, piiMiddleware } from "langchain";

export const agent = defineDeepAgent({
  name: "support-agent",
  model: "openai:gpt-5.5",
  middleware: [
    piiMiddleware("email", { strategy: "redact", applyToInput: true }),
    modelCallLimitMiddleware({ runLimit: 50 }),
  ],
});

커스텀 미들웨어 정의하기 (선택) (Define custom middleware (Optional))

더 고급 옵션의 경우 로컬 모듈에서 커스텀 미들웨어를 정의합니다.

import { createMiddleware } from "langchain";

export const logToolCalls = createMiddleware({
  name: "LogToolCalls",
  wrapToolCall: async (request, handler) => {
    console.log(`Calling tool: ${request.toolCall.name}`);
    const result = await handler(request);
    console.log(`Finished tool: ${request.toolCall.name}`);
    return result;
  },
});

미들웨어를 프로젝트 루트 에이전트 진입점으로 가져오고 middleware 목록에 전달합니다:

import { defineDeepAgent } from "managed-deepagents";

import { logToolCalls } from "./middleware/audit";

export const agent = defineDeepAgent({
  name: "support-agent",
  model: "openai:gpt-5.5",
  middleware: [logToolCalls],
});

미들웨어 가져오기는 일반 로컬 TypeScript 프로젝트에서와 같은 방식으로 작동해야 합니다.

런타임 컨텍스트 사용하기 (Use runtime context)

미들웨어는 일반 LangChain 런타임 API를 통해 실행별 컨텍스트를 읽을 수 있습니다. 사용자 ID, 조직 ID, 기능 플래그, 요청 메타데이터, 또는 기본적으로 모델 프롬프트에 포함되어서는 안 되는 자격증명에 컨텍스트를 사용하세요.

예시는 커스텀 미들웨어를 참고하세요.

배포 (Deployment)

mda dev와 mda deploy는 middleware/ 아래의 모듈을 포함해 프로젝트 파일을 컴파일된 빌드로 복사합니다. 미들웨어는 Context Hub에 동기화되지 않습니다. 에이전트 코드와 함께 제공됩니다.

미들웨어를 사용할 때 (When to use middleware)

개념 (Concept) 종류 (Kind) 에이전트에 도달하는 방식 (How it reaches the agent)
미들웨어 (Middleware) 애플리케이션 코드 에이전트 정의에 가져와 전달
커스텀 도구 (Custom tools) 애플리케이션 코드 에이전트 정의에 가져와 전달
지시사항 (Instructions) 관리 컨텍스트 항상 켜져 있는 시스템 프롬프트

자세한 내용은 프로젝트 구조를 참고하세요.

더 알아보기 (Learn more)