> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/a2a/gateway.md). # 에이전트 게이트웨이 MCP 서버와 A2A 에이전트로 들어오는 호출을 누가·어떤 도구까지·분당 몇 번 쓸 수 있는지 정하고, 문제가 생겼을 때 즉시 끊고 무엇이 막혔는지 확인하는 방법을 안내합니다. 행위 라벨(파괴적·외부연동 등)을 지정하는 방법은 MCP 도구 라벨링 사용자 매뉴얼을, 구현 구조와 API 계약은 에이전트 게이트웨이 설계를 참고하세요. ## 목차 1. [게이트웨이가 하는 일](#게이트웨이가-하는-일) 2. [메뉴와 권한](#메뉴와-권한) 3. [대상 목록 보기](#대상-목록-보기) 4. [대상의 기본 정보 확인하기](#대상의-기본-정보-확인하기) 5. [기본 설정 정하기](#기본-설정-정하기) 6. [행위 라벨별 설정하기](#행위-라벨별-설정하기) 7. [도구별 설정하기](#도구별-설정하기) 8. [호출자별 정책 만들기](#호출자별-정책-만들기) 9. [설정이 겹칠 때 무엇이 이기는지](#설정이-겹칠-때-무엇이-이기는지) 10. [비상 차단하기](#비상-차단하기) 11. [모니터링하기](#모니터링하기) 12. [차단된 호출자에게 보이는 메시지](#차단된-호출자에게-보이는-메시지) 13. [표시가 예상과 다를 때](#표시가-예상과-다를-때) ## 게이트웨이가 하는 일 에이전트 게이트웨이는 MCP 서버·A2A 에이전트 호출이 대상에 닿기 전에 세 가지를 판단합니다. | 판단 | 내용 | | ------ | --------------------------- | | 비상 차단 | 지금 이 대상 또는 이 호출자를 끊어 둔 상태인가 | | 허용 여부 | 이 호출자가 이 도구를 부를 수 있는가 | | 호출량 한도 | 분당 허용 횟수를 넘지 않았는가 | 정책이 적용되는 대상은 관리자가 따로 등록하지 않습니다. MCP 서버와 A2A 에이전트를 등록하면 게이트웨이 대상 목록에 자동으로 나타납니다. 브라우저 로그인 토큰으로 리소스를 직접 호출하는 경우에도 사용자·관리그룹 기준 정책과 비상 차단이 그대로 적용됩니다. 채팅을 거치지 않은 직접 호출로 정책을 우회할 수는 없습니다. ## 메뉴와 권한 LNB **에이전트 게이트웨이** 아래에 두 메뉴가 있습니다. | 메뉴 | 내용 | | -------- | -------------------------- | | 접근 정책 관리 | 대상 목록, 대상 상세, 정책 편집, 비상 차단 | | 모니터링 | 호출자 목록, 연결 토폴로지, 차단 로그 | 권한 구성 화면의 「에이전트 게이트웨이」 카테고리는 **정책 관리 · 모니터링 · 비상 차단** 3항목입니다. 비상 차단은 별도 메뉴가 아니라 대상 상세의 탭이므로 LNB에는 2항목만 보입니다. 비상 차단 권한이 없으면 대상 상세에서 **비상 차단** 탭 자체가 보이지 않습니다. ## 대상 목록 보기 **에이전트 게이트웨이 > 접근 정책 관리**에서 대상 목록을 확인합니다.

| 열 | 내용 | | ---------------- | ------------------------------------------------- | | 이름 | 대상 이름 | | 유형 | 이 대상이 열려 있는 경로. MCP 서버·A2A 에이전트 배지로 표시합니다. | | 도구·기능 | 대상이 제공하는 도구 이름 | | 호출자 정책 | 이 대상에 만들어 둔 호출자별 정책 건수. 숫자를 누르면 상세의 해당 탭으로 이동합니다. | | 관리그룹 · 생성자 · 생성일 | 대상 리소스의 소유 정보 | | 배포 상태 | 배포 / 미배포 | | 차단 상태 | 비상 차단 중 / 특정 차단 중 / 차단 없음 | 이름·생성자·관리그룹으로 검색하고, 유형·**배포된 대상만 보기**·**비상 차단 중인 대상만 보기**로 좁힐 수 있습니다. 하나의 워크플로우가 MCP 서버와 A2A 에이전트 양쪽으로 열려 있으면 **한 행의 유형 열에 배지가 두 개** 표시됩니다. 행이 두 줄로 나뉘지는 않습니다. **대상 행을 더블클릭하면** 상세 화면이 열립니다. 한 번 클릭으로는 열리지 않습니다. ## 대상의 기본 정보 확인하기 대상 상세에는 **기본 정보 · 접근 정책 · 비상 차단** 탭이 있습니다.

**기본 정보**에서 이름·설명·유형·기반 리소스·관리그룹·생성자·생성일·배포 상태를 확인합니다. **도구·기능** 영역에서 대상이 제공하는 도구를 봅니다. 파괴적·외부연동 라벨을 가진 도구는 강조 표시되고, **위험 도구 N개** 배지로 개수를 함께 보여줍니다. 차단 설정을 켜면 이 도구들이 막힙니다. ## 기본 설정 정하기 **접근 정책** 탭의 **기본 설정**은 별도 정책이 없는 모든 호출자에게 적용되는 값입니다.

오른쪽 위 **수정**을 누르면 「정책 편집」 패널이 열립니다.

호출량 한도는 개별 설정이 **허용**일 때만 입력할 수 있습니다. 기본 설정을 **기본값**으로 두면 상위 설정이 없으므로 아무 정책도 적용되지 않고 호출이 그대로 통과합니다. 패널에도 같은 안내가 표시됩니다. 막으려면 **차단**을 명시적으로 선택해야 합니다. ## 행위 라벨별 설정하기 **행위 라벨별 설정**에서는 도구를 하나하나 지정하지 않고 도구가 가진 행위 라벨로 정합니다. 접힌 상태로 시작하므로 **펼치기**를 눌러 엽니다.

| 축 | 라벨 | 설정 | | ---- | --------- | ------------ | | 차단 축 | 파괴적, 외부연동 | 차단 / 기본값(상속) | | 허용 축 | 읽기전용, 멱등성 | 허용 / 기본값(상속) | 차단 조건과 허용 조건이 동시에 맞으면 **차단이 우선**합니다. 기본값(상속)으로 두면 상위 설정을 따릅니다. 차단을 켜면 저장 전에 **이 설정을 저장하면 도구 N개가 차단됩니다**로 영향 범위가 표시됩니다. 저장 전에 이 숫자를 확인하세요. 행위 라벨이 지정되지 않은 도구는 이 설정으로 걸리지 않습니다. 라벨을 먼저 지정해야 합니다. ## 도구별 설정하기 **도구별 설정**에서는 특정 도구만 별도로 허용·차단하거나 호출량을 제한합니다. 도구·설명·행위 라벨·개별 설정·호출량 한도·호출자 예외를 한 표에서 봅니다. 도구 행의 **호출자 예외**를 누르면 그 도구를 기본 설정과 다르게 지정한 호출자 목록을 확인할 수 있습니다. 정책 편집 중에는 열 수 없습니다. 저장 전 값과 목록이 어긋나는 것을 막기 위한 동작입니다. ## 호출자별 정책 만들기 **호출자별 정책**에서 특정 사용자·관리그룹·인증키에만 다른 정책을 적용합니다. 표에서 호출자·구분·정책 사용·개별 설정·허용 도구·연결일시를 확인하고, **정책 추가**로 새 정책을 만듭니다.

호출자 유형은 다음과 같습니다. | 유형 | 내용 | | ---- | --------- | | 사용자 | 로그인 계정 | | 관리그룹 | 계정이 속한 그룹 | | 인증키 | 발급된 API 키 | 인증키는 **이 대상에 발급된 키만** 선택할 수 있습니다. 발급된 키가 없으면 먼저 대상 상세 화면의 「인증 키」에서 발급하세요. 사용자·관리그룹은 전체에서 선택합니다. 호출자를 고른 뒤 기본 설정·행위 라벨별 설정·도구별 설정을 기본 설정과 같은 방식으로 지정합니다. 에이전트는 정책 대상이 아니라 관측 축입니다. 정책은 진입 호출자(사용자·관리그룹·인증키) 기준으로 걸리고, 그 정책이 에이전트가 대신 부르는 구간까지 적용됩니다. **정책 사용**을 끄면 설정은 남아 있지만 그 호출자에게 적용되지 않습니다. 목록에는 **미사용(미집행)** 배지가 표시됩니다. 정책을 삭제하면 그 호출자는 기본 설정을 따릅니다. A2A 에이전트로 노출된 대상에는 경고가 표시됩니다. A2A 요청에는 도구 식별자가 없어 **도구별 설정과 행위 라벨별 설정이 A2A 경로에서는 집행되지 않습니다.** 기본 설정과 호출자별 차단은 A2A 경로에서도 정상 동작합니다. MCP·A2A 겸용 대상은 MCP 경로에서만 두 설정이 적용됩니다. ## 설정이 겹칠 때 무엇이 이기는지 허용 여부와 호출량 한도는 판단 방식이 다릅니다. 이 차이를 알아야 화면의 설정과 실제 동작이 맞습니다. **허용 여부 — 좁은 것이 이깁니다.** 호출자 계층은 `사용자 > 인증키 > 관리그룹 > 기본 설정` 순으로 먼저 말하는 계층이 이깁니다. 한 계층 안에서는 `도구별 > 행위 라벨별 > 기본 설정` 순으로 뒤가 앞을 덮습니다. 기본값(상속)으로 둔 항목은 판단하지 않고 넘어가 다음 계층이 결정합니다. 그래서 「관리그룹은 차단인데 이 사람만 허용」이나 「기본은 차단, 이 호출자만 허용」 같은 예외를 만들 수 있습니다. **호출량 한도 — 가장 엄격한 값이 적용됩니다.** 기본 설정과 도구별 설정에 각각 한도가 있으면 둘 다 검사하고 더 작은 값에서 먼저 막힙니다. 좁은 계층이 넓은 계층의 한도를 늘려 주지는 않습니다. **비상 차단은 정책보다 앞섭니다.** 비상 차단이 걸려 있으면 정책이 허용이어도 막힙니다. ## 비상 차단하기 **비상 차단** 탭에서 지금 즉시 호출을 끊습니다. 차단 실행 즉시 요청이 거부되고 진행 중인 응답도 중단됩니다.

| 범위 | 조작 | | ------- | --------------------------------------------- | | 전체 차단 | **전체 차단** / **전체 해제**로 이 대상의 모든 호출을 차단·해제합니다. | | 호출자별 차단 | **호출자 차단 추가**로 선택한 호출자의 호출만 차단합니다. | **전체 차단과 호출자별 차단은 서로 독립입니다.** 전체 차단을 해제해도 호출자별 차단은 그대로 남습니다. 화면 상단에도 같은 안내가 표시됩니다. 두 곳을 각각 확인하세요. 차단·해제에는 사유 입력이 필수입니다. 사유는 차단 이력에 그대로 남습니다. 호출자별 차단 표에서는 범위·차단 호출자·차단 사유·차단 일시·차단 수·해제를 확인합니다. 이미 차단 중인 호출자에는 **차단 중** 표시가 붙습니다. ### 차단 이력 확인하기 **차단 이력**에서 구분(차단/해제)·범위(전체/특정 N)·차단 호출자·사유·차단 일시·조치자·해제 일시를 확인합니다. 조치자가 **AIM 자동**인 항목은 사람이 아니라 자동 판단으로 걸린 차단입니다. 이력에서 여러 건을 선택해 같은 사유로 한 번에 해제할 수 있습니다. 두 가지를 유의하세요. * **전체 선택**은 현재 페이지의 건수만 선택합니다. 다른 페이지의 차단은 해제되지 않습니다. * 검색에서 **차단 호출자**는 전체에서 찾지만 **사유**는 현재 페이지에서만 추리는 보조 필터입니다. 총 건수와 다르게 보일 수 있습니다. ## 모니터링하기 **에이전트 게이트웨이 > 모니터링**에서 게이트웨이가 처리한 호출을 확인합니다. 탭은 **호출자 목록 · 연결 토폴로지 · 차단 로그** 3개입니다. 기간을 지정하지 않으면 **최근 30일**만 조회합니다. ### 호출자 목록 게이트웨이가 관측한 호출자를 최초·최근 호출일시와 함께 보여줍니다. 상단 카드에 전체 호출자 수가 표시됩니다.

| 열 | 내용 | | ------- | ----------------------------------------- | | 유형 | 사용자 / 관리그룹 / 인증키 / 에이전트 | | 관측 대상 수 | 이 호출자의 호출이 관측된 대상 수. 누르면 대상 목록을 봅니다. | | 허용 건수 | 허용된 호출 건수 | | 차단된 호출 | 정책·비상 차단으로 막힌 호출 건수. 대상 수가 아닙니다. | | 정책 | 없음 / 전용 정책 있음 / 기본 정책 적용 / 일부 대상 정책 (N/M) | | 비상 차단 | 차단 없음 / 차단 중 / 대상 전체 차단 / 일부 대상 차단 (N/M) | 집계는 **최대 1분 지연**됩니다. MCP는 도구 호출(`tools/call`)만 셉니다. **정책** 열과 **비상 차단** 열은 서로 다른 것을 봅니다. 정책으로 막힌 호출은 비상 차단 열에 표시되지 않습니다. **차단된 호출** 열을 보세요. 「일부 대상 정책」·「일부 대상 차단」 배지는 누르면 어느 대상이 해당하는지 확인할 수 있습니다. 호출자 정보가 없는 차단은 이 목록에서 제외되고 건수만 안내됩니다. 해당 건은 차단 로그 탭에서 확인하세요. ### 연결 토폴로지 **기준 대상 선택**으로 대상 하나를 고르면 그 대상을 중심으로 **들어오는 호출 · 기준 대상 · 나가는 호출** 세 구간을 그려 줍니다. 기준 대상을 선택하지 않으면 그래프가 표시되지 않습니다.

범례는 기준 대상, 비상 차단된 대상, 정상 호출, 대상 간 호출, 차단된 적 있음, 비상 차단 중으로 구분됩니다. 노드와 연결선의 숫자는 호출 건수입니다. 같은 대상이 들어오는 호출과 나가는 호출에 함께 있으면 순환 호출 안내가 표시됩니다. 연결이 많으면 최근 것만 표시하고 안내 문구가 나옵니다. 기간이나 대상을 좁혀서 보세요. ### 차단 로그 **이 목록에는 차단된 호출만 기록됩니다. 허용된 호출은 남지 않습니다.**

차단 시간·호출자·대상·도구·요청 ID·차단 형태를 확인하고, **상세**를 열면 차단 사유와 대상 리비전 ID를 볼 수 있습니다. 대상 검색, 차단 형태, 기간으로 좁힐 수 있습니다. 차단 형태는 다음과 같습니다. | 차단 형태 | 의미 | | ----- | -------------------- | | 정책 차단 | 접근 정책의 차단 설정에 걸렸습니다. | | 한도 초과 | 분당 호출량 한도를 넘었습니다. | | 비상 차단 | 비상 차단이 적용된 상태입니다. | | 인증 실패 | 호출자 인증이 실패했습니다. | | 대상 오류 | 대상 쪽 응답이 실패했습니다. | 차단 로그에는 적중한 정책의 범위와 사유가 함께 남습니다. 어떤 계층에서 막혔는지 상세에서 확인하세요. ## 차단된 호출자에게 보이는 메시지 차단 사유에 따라 호출자에게 전달되는 메시지가 다릅니다. 문의를 받았을 때 어느 설정 때문인지 바로 판단할 수 있습니다. | 메시지 | 원인 | | ---------------------- | -------------------- | | 비상 차단으로 호출이 중지되었습니다. | 전체 차단 또는 호출자별 차단 | | 접근 정책에 의해 호출이 거부되었습니다. | 기본·행위 라벨별·도구별 설정의 차단 | | 호출량 한도를 초과했습니다. | 분당 호출량 한도 초과 | ## 표시가 예상과 다를 때 **대상을 클릭했는데 상세가 열리지 않습니다.** 목록은 더블클릭으로 상세를 엽니다. 한 번 클릭으로는 열리지 않습니다. **설정을 차단으로 바꿨는데 호출이 통과합니다.** 좁은 계층에 허용이 남아 있는지 확인하세요. 사용자·인증키·관리그룹 정책이 기본 설정보다 먼저 판단합니다. A2A 경로라면 도구별·행위 라벨별 설정은 집행되지 않습니다. **행위 라벨별 차단을 켰는데 특정 도구가 막히지 않습니다.** 그 도구에 해당 라벨이 지정돼 있는지 확인하세요. 라벨이 없으면 걸리지 않습니다. 도구별 설정에 허용이 지정돼 있으면 라벨 설정보다 우선합니다. **전체 차단을 해제했는데 여전히 막힙니다.** 호출자별 차단이 남아 있을 수 있습니다. 두 차단은 독립입니다. **모니터링에 아무 기록도 없습니다.** 게이트웨이 정책 집행이 꺼져 있으면 호출·차단이 전혀 기록되지 않습니다. 게이트웨이(`gateway-api`) 환경 변수 `AGENT_GATEWAY_POLICY_ENABLED` 가 켜져 있는지 확인하세요. 기간을 지정하지 않으면 최근 30일만 조회하는 점도 함께 확인하세요. **허용 건수가 실제보다 적게 보입니다.** 집계는 최대 1분 지연됩니다. MCP는 도구 호출만 세므로 도구를 부르지 않은 요청은 반영되지 않습니다. **비상 차단을 걸었는데 헬스체크와 중지 동작은 계속 됩니다.** 의도된 동작입니다. 상태 확인 경로와 실행 중지(`/run/abort`) 경로는 정책 평가에서 제외됩니다. 이 경로까지 막으면 차단을 걸어도 진행 중인 응답을 멈출 수 없고 배포 상태가 전부 비정상으로 표시됩니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/a2a/gateway.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.