이전 페이지에서는 기술 패키지가 사용 가능한 도메인 전문 지식(지침, 참조 자료 및 스크립트)을 모든 에이전트가 주문형으로 로드할 수 있는 자체 포함 단위로 패키지하는 방법을 보여 줍니다. 그러나 에이전트를 프로덕션에 배포하면 에이전트가 수행하는 작업과 관계없이 모든 상호 작용을 중단하는 문제라는 새로운 범주의 문제가 발생합니다.
모든 요청 및 응답을 기록해야 합니다. 모델이 이를 확인하려면 유해한 콘텐츠를 차단하는 가드레일이 필요합니다. 에이전트의 핵심 논리를 변경하지 않고도 속도 제한을 적용하고, 예외를 깔끔하게 처리하며 원격 분석을 주입해야 합니다. 이러한 문제를 모든 에이전트(또는 모든 도구 또는 모든 기술)에 복사하여 붙여넣으면 확장에 한계가 있고, 유지 관리에 상당한 어려움이 발생합니다.
미들웨어 는 이를 해결합니다. 미들웨어를 사용하면 잘 정의된 지점에서 요청 및 응답을 가로채고, 검사하고, 수정하는 재사용 가능한 동작으로 에이전트의 실행 파이프라인 을 래핑할 수 있습니다. 미들웨어를 에이전트 주변의 일련의 동심 계층으로 간주합니다. 각 계층은 에이전트에 도달하기 전에 입력에 대해, 그리고 호출자에게 도달하기 전에 출력에 대해 작업할 기회를 얻습니다.
이것을 사용해야 하는 경우
다음과 같은 경우 에이전트에 미들웨어를 추가합니다.
- 모델에서 처리하는 전후에 유해하거나 토픽이 없거나 정책을 위반하는 콘텐츠를 차단하려면 가드레일 이 필요합니다.
- 각 에이전트를 개별적으로 수정하지 않고 모든 에이전트 상호 작용에 대한 중앙 집중식 로깅 또는 원격 분석을 원합니다.
- 에이전트 논리를 변경하지 않고 요청 또는 응답을 수정 해야 합니다. 즉, 프롬프트를 보강하거나, 출력을 변환하거나, 결과를 완전히 바꿔야 합니다.
- 모든 실행에 적용되는 속도 제한, 콘텐츠 필터링 또는 인증 검사와 같은 정책을 적용 하려고 합니다.
- 일시적인 오류에 대한 재시도, 정상 대체 응답 반환 또는 진단에 대한 로깅 오류 등 예외를 일관되게 처리 해야 합니다.
- 여러 미들웨어 구성 요소에 필요한 요청 타이밍 추적 또는 메트릭 누적과 같이 파이프라인 전체에서 상태를 공유 하려고 합니다.
팁 (조언)
에이전트 프레임워크에는 추적 및 측정 지표에 대한 기본 제공 계측 기능이 포함되어 있습니다. 자세한 내용은 Observability 를 참조하세요.
미들웨어 파이프라인 작동 방식
에이전트의 실행 메서드를 호출하면 요청이 모델로 직접 이동하지 않습니다. 대신, 각각 요청을 검사하거나 수정하고, 다음 계층에 위임한 다음, 돌아오는 길에 응답을 검사하거나 수정할 수 있는 미들웨어 계층의 파이프라인을 통해 전달됩니다.
┌─────────────────────────────────────────────────────────┐
│ Caller: agent.run("What's the weather?") │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Middleware 1 (Logging) │
│ • Logs the incoming request │
│ • Calls next middleware │
│ • Logs the outgoing response │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Middleware 2 (Guardrails) │
│ • Checks input against content policy │
│ • If blocked → returns early with rejection message │
│ • If allowed → calls next middleware │
│ • Checks output against content policy │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Agent core (model invocation, tool calls, etc.) │
└─────────────────────────────────────────────────────────┘
핵심 사항:
- 각 미들웨어는 계속할지 여부를 결정합니다. 미들웨어는 체인의 다음 계층을 호출하여 정상적으로 진행하거나, 예를 들어 가드레일이 요청을 차단하는 경우 응답을 직접 반환하여 파이프라인을 단락할 수 있습니다.
- 미들웨어는 양방향을 봅니다. 미들웨어는 입력을 검사하거나 수정하기 전에 코드를 실행하고 응답이 다시 돌아온 후 (출력을 검사하거나 수정하기 위해) 코드를 실행합니다. 이것은 고전적인 "양파"패턴입니다.
- 여러 미들웨어 체인이 함께 연결됩니다. 여러 미들웨어 구성 요소를 등록할 때 중첩됩니다. 등록된 첫 번째 미들웨어 구성 요소는 가장 바깥쪽 계층이고, 마지막으로 등록된 것은 가장 안쪽 계층으로 에이전트와 가장 가깝습니다.
팁 (조언)
컨텍스트 공급자 및 채팅 클라이언트 계층을 포함하여 미들웨어가 전체 에이전트 실행 파이프라인에 어떻게 부합하는지에 대한 자세한 내용은 에이전트 파이프라인 아키텍처를 참조하세요.
미들웨어에서 수행할 수 있는 일
Agent Framework는 파이프라인의 세 계층(에이전트 실행, 함수 호출 및 채팅 클라이언트)에서 미들웨어를 지원하므로 실행을 가로채는 위치를 세밀하게 제어할 수 있습니다. 일반적인 패턴은 다음과 같습니다.
| 패턴 | 예시 | 참조 |
|---|---|---|
| 가드레일 및 종료 | 유해한 콘텐츠 차단, 대화 길이 제한 | 종료 및 보호 장치 |
| 예외 처리 | 일시적 오류에 대한 재시도, 대체 응답 반환 | 예외 처리 |
| 결과 우선 적용 | 중요한 데이터 수정, 에이전트 출력 보강 또는 바꾸기 | 결과 재정의 |
| 공유 상태 | 미들웨어 간에 요청 ID 또는 타이밍 데이터 전달 | 공유 상태 |
| 런타임 컨텍스트 | 세션, 사용자 또는 실행별 구성에 따라 동작 변경 | 런타임 컨텍스트 |
| 범위 지정 | 모든 실행 또는 단일 실행에 미들웨어 적용 | 에이전트 및 실행 범위 |
미들웨어 정의 및 등록에 대한 전체 연습은 미들웨어 정의를 참조하세요. 전체 아키텍처 개요는 미들웨어 개요를 참조하세요.
고려 사항
| 고려 사항 | 세부 정보 |
|---|---|
| 우려 사항 분리 | 미들웨어는 교차 절단 로직을 에이전트 코드, 도구 및 기술에서 분리시킵니다. 각 미들웨어 구성 요소는 개별적으로 추가, 제거 또는 다시 정렬할 수 있는 로깅, 가드레일, 오류 처리 등의 단일 책임이 있습니다. |
| 순서 의존성 | 미들웨어는 체인을 형성합니다. 미들웨어를 등록하는 순서는 중요합니다. 먼저 실행되는 로깅 미들웨어에는 원시 입력이 표시되며, 마지막으로 실행되는 미들웨어는 이전 미들웨어에서 이미 수정한 입력을 볼 수 있습니다. 파이프라인의 순서를 신중하게 계획하세요. |
| 디버깅 복잡성 | 미들웨어가 입력 또는 출력을 수정하는 경우 디버깅을 수행하려면 전체 파이프라인을 이해해야 합니다. 에이전트 때문이 아니라 미들웨어가 변환했기 때문에 응답이 잘못 보일 수 있습니다. 좋은 로깅 미들웨어(체인 초기에 배치)는 이러한 사례를 진단하는 데 도움이 됩니다. |
| 성능 오버헤드 | 각 미들웨어 계층은 모든 요청에 처리 시간을 추가합니다. 로깅과 같은 간단한 작업의 경우 무시할 수 있습니다. 외부 콘텐츠 조정 API 호출과 같은 비용이 많이 드는 작업의 경우 대기 시간이 더해집니다. 특히 이러한 여러 미들웨어가 연결된 경우 더해집니다. |
다음 단계
이제 에이전트에 도구, 기술 및 미들웨어가 있으므로 다음 단계는 각 실행 전에 메모리, 사용자 프로필 및 동적 지식을 에이전트의 컨텍스트 창에 삽입하는 구성 요소인 컨텍스트 공급자 입니다.
더 자세히 살펴보기:
- 미들웨어 개요 - 모든 미들웨어 유형에 대한 전체 참조
- 에이전트 파이프라인 아키텍처 - 미들웨어가 실행 파이프라인에 맞는 방법