이 가이드에서는 OpenAPI 3.0 문서를 에이전트 도구로 변환하는 방법을 배울 수 있습니다. agentengine agent create-tool 명령을 사용하여 문서를 커넥터 파일로 컴파일합니다. 에이전트를 빌드하면 Atlas 에이전트 엔진이 해당 파일에서 커넥터를 생성하여 에이전트가 OpenAPI 에이전트 도구를 호출할 수 있도록 합니다.
참고
agentengine agent create-tool 명령은 실험적입니다. 플래그, 출력 형식 및 생성된 파일 형식은 예고 없이 변경될 수 있습니다.
이 작업에 관한 정보
agentengine agent create-tool 명령은 지정한 폴더에 두 개의 파일을 생성합니다.
tool_defs.yaml: 명령이 OpenAPI 문서에서 컴파일하는 도구 카탈로그입니다. 카탈로그에는 각 작업에 대한 도구 이름, 입력 스키마, HTTP 메서드 및 경로가 포함되어 있습니다.tool.yaml: 카탈로그를 API 엔드포인트 및 자격 증명에 바인딩하고 에이전트가 노출할 도구를 선택하는 작성 파일입니다. 이 명령은 이 파일을 스캐폴딩합니다. 카탈로그를 다시 생성할 때 이 명령은 파일에 대한 편집 내용을 덮어쓰지 않습니다.
에이전트가 커넥터 도구를 호출하면 해당 도구는 격리된 Tool Pod에서 실행됩니다. 이 호출하다은 다른 도구와 동일한 Orchestration 엔진 승인 게이트를 통과합니다. 자격 증명 값은 생성된 파일에 기록되지 않으며, 파일은 대신 작업 영역 비밀의 이름을 참조합니다.
명령어에 다음 입력 중 정확히 하나를 전달해야 합니다.
--spec: OpenAPI 3.0 문서를 카탈로그로 컴파일하고tool.yaml파일이 없는 경우 스캐폴딩합니다. 값은 로컬 파일 또는 HTTPS URL일 수 있습니다.--tool-defs: 기존 로컬 카탈로그에 대해tool.yaml파일만 스캐폴딩합니다. 이 명령은 카탈로그를 다시 작성하지 않습니다.--config:source.spec필드를 선언하는tool.yaml파일에서 로컬로 소유한 카탈로그를 재생성합니다.
모든 플래그를 보려면 agentengine_create-tool CLI 설명서를 참조하세요.
시작하기 전에
시작하기 전에 다음 리소스가 준비되어 있는지 확인하세요.
agentengineCLI가 설치되고 인증되었습니다. 학습 내용은 설치 및 인증을 참조하세요.agent.yaml파일이 포함된 유효한 에이전트 프로젝트입니다. 자세히 알아보려면 프로젝트 만들기를 참조하세요.Docker가 로컬에서 실행 중입니다.
호출하려는 REST API에 대한 OpenAPI 3.0 문서(로컬 파일 또는 HTTPS URL).
REST API를 위한 인증 Bearer token입니다.
단계
커넥터 파일을 생성합니다.
에이전트 프로젝트 디렉토리에서 커넥터 이름과 --spec 플래그를 사용하여 agentengine agent create-tool 명령을 실행합니다. 다음 예시는 사양을 connectors/orders 폴더로 컴파일하고 Bearer token 인증을 구성합니다.
agentengine agent create-tool orders \ --spec <openapi-document-url-or-path> \ --out-dir connectors/orders \ --auth bearer이 명령어는 커넥터의 이름을 따서 Bearer token에 대한 작업 영역 보안 비밀의 이름을 지정합니다. orders 커넥터의 경우 보안 비밀 이름은 ORDERS_TOKEN입니다. --auth 플래그를 생략하면 명령어는 문서에 선언된 보안 체계에서 tool.yaml 파일의 auth 블록을 생성합니다.
이 명령은 문서에서 템플릿이 아닌 첫 번째 서버를 기본 URL로 사용합니다. 문서에 서버가 선언되어 있지 않거나 다른 엔드포인트를 호출하려는 경우 명령에 --base-url 플래그를 추가하세요.
문서에 생성기가 표현할 수 없는 작업이 포함되어 있으면 명령이 실패하고 작업 이름이 출력됩니다. 대신 해당 작업을 제외하려면 명령에 --skip-unsupported 플래그를 추가하세요. 명령은 건너뛴 모든 작업을 출력하고 카탈로그에 기록합니다.
tool.yaml 파일 검토합니다.
connectors/orders/tool.yaml 파일을 엽니다. 파일 상단의 주석은 에이전트가 선언해야 하는 엔드포인트 대상과 자격 증명 비밀을 명시합니다.
에이전트가 호출할 수 있는 도구를 제한하려면 expose.allow 필드에 특정 도구 이름을 나열하세요. 이 목록을 생략하면 에이전트가 생성된 모든 도구를 호출할 수 있습니다. 다음 예시는 하나의 도구를 노출하는 tool.yaml 파일을 보여줍니다.
name: orderstool_defs: tool_defs.yamlsource: type: openapi base_url: https://api.example.comexpose: allow: [orders_getOrder]auth: bearer: ORDERS_TOKENAPI 자격 증명을 워크스페이스 보안 비밀로 저장합니다.
tool.yaml 파일의 auth 블록이 참조하는 이름으로 보안 비밀을 생성합니다. 이 예시에서 보안 비밀 이름은 ORDERS_TOKEN입니다. 비밀을 저장하는 방법을 학습하려면 클라우드 비밀 프로비저닝을 참조하세요.
도구 샌드박스에 비밀 및 API에 대한 액세스 권한을 부여합니다.
tool.yaml 파일 상단의 주석은 요구 사항만 보고하며 권한을 부여하지 않습니다. agent.yaml 파일의 sandboxes.tool.secrets 필드에 비밀을 추가하고 sandboxes.tool.network.egress 필드에 API 호스팅 주소를 추가합니다. 다른 도구에서 이미 사용하는 비밀과 대상을 유지합니다. 다음 예시에서는 ORDERS_TOKEN 비밀과 api.example.com 호스팅하다을 추가합니다.
sandboxes: tool: secrets: - ORDERS_TOKEN network: egress_mode: allow_list egress: - fqdn: api.example.com ports: [443]tool.yaml 파일의 기본 URL 호스트 이름과 포트로 api.example.com 및 443을(를) 바꿉니다. 자세한 내용은 에이전트 YAML 스키마 및 네트워크 송신 정책 관리를 참조하세요.
에이전트를 빌드하고 배포합니다.
평소와 같이 에이전트를 빌드하고 배포합니다. 빌드는 tool.yaml 및 tool_defs.yaml 파일에서 커넥터를 생성합니다. 자세한 내용을 학습하려면 에이전트 이미지 빌드를 참조하세요.
동작 및 제한 사항
생성된 커넥터 도구에 대한 다음 동작 및 제한 사항을 검토합니다.
tool.yaml파일의 기본 URL은 모든 작업에 적용됩니다. 생성기는 OpenAPI 문서의 경로 수준 및 작업 수준servers항목을 무시합니다.생성기는 로컬 파일을 읽습니다. CLI는 플랫폼 전송 정책에 따라 URL로 지정한 문서를 다운로드합니다.
이 생성기는 Bearer token, API 키 및 HTTP Basic 인증을 지원합니다. 다음은 생성 경계 외부에 있습니다.
OAuth 토큰 획득 및 갱신
대화형 또는 세션 로그인
요청별 서명
mTLS 전용 인증
멀티파트 파일 업로드
커넥터는 200,000 디코딩된 바이트보다 큰 응답을 잘라내고 잘린 것으로 표시합니다.
각 도구 호출은 30 초 후에 시간 초과됩니다.
자세히 알아보기
OpenAPI 도구에 대해 자세히 알아보려면 다음 문서를 참조하세요.
agentengine_create-tool