Agent Resource Data 런타임
Core가 App 소유 Resource·permission·schema·route·controller 계약에서 일반 Agent 읽기·쓰기 도구를 만드는 방식입니다.
Agent Resource Data 런타임
App의 Resource를 Agent에서도 읽고 수정할 수 있게 준비합니다. Resource 만들기에 따라 모델·권한·필드·API를 먼저 구현하세요. Core가 이 선언에서 지원 가능한 작업을 찾으므로 App마다 일반 데이터 도구를 따로 만들 필요는 없습니다.
App에서 준비할 것
Resource 카탈로그에 Eloquent 모델과 PermissionContribution을 함께 제공해야 합니다. 둘 중 하나라도 없으면 일반 데이터 접근 대상에서 제외됩니다. Resource descriptor에 필드의 의미와 타입을 선언하고, 목록 스키마에 필터·정렬·검색 기능을 정의하세요.
쓰기 작업은 Resource의 기존 컨트롤러를 사용합니다. Note 모델에는 같은 App 네임스페이스의 NoteController가 대응해야 합니다. 생성은 GET 목록과 같은 URI의 POST, 수정은 GET 상세와 같은 URI의 PUT 또는 PATCH, 삭제는 그 상세 URI의 DELETE로 연결됩니다. Resource 생성기가 이 구조를 제공합니다.
Agent가 사용하는 도구
| 도구 | 하는 일 |
|---|---|
data.catalog | 현재 사용자가 접근할 수 있는 Resource 탐색 |
data.describe | 필드, 지원 작업, 필터, 정렬, 검색, 참조 정보와 상태 전환 동작 조회 |
data.query | 테넌트와 Resource 권한을 확인한 뒤 제한된 범위 조회 |
data.detail | App의 인가된 상세 API를 통해 업무 DTO를 포함한 한 건 조회 |
data.preview | 선언된 읽기 전용 업무 검사를 정확한 HTTP 메서드와 입력 스키마로 실행 |
data.verify | 데이터를 변경하지 않고 제안된 쓰기를 건별 사전 검사 |
data.mutate | 승인된 생성·수정·삭제 한 건을 Resource API로 실행 |
data.mutate_batch | 승인된 계획을 순서대로 실행하고 건별 결과 기록 |
data.action | 승인 후 Resource의 전용 API로 제출·취소 등 선언된 동작 실행 |
필드 설명은 ResourceDescriptor, Resource Transfer 컬럼, DB 스키마 순서로 적용합니다. 응답의 field_source로 명시적인 선언인지 DB에서 추론한 값인지 구분할 수 있습니다. 필터·정렬·검색은 DB 컬럼을 보고 추측하지 않고 목록 스키마를 따릅니다.
컨트롤러나 대응하는 읽기·쓰기 경로가 없거나 후보가 여러 개면 해당 작업은 지원되지 않습니다. Core가 모델에 직접 쓰지 않으므로 기존 요청 검증, Policy, 트랜잭션, 도메인 서비스와 이벤트가 계속 실행됩니다. {legalEntity:public_id} 같은 경로 바인딩에는 신뢰된 위임 문맥을 사용합니다.
중첩 Resource는 해석된 부모 경로 안에서만 접근할 수 있습니다. 부모가 필요한 레코드를 최상위 레코드처럼 조회하거나 수정할 수 없습니다.
일괄 작업은 승인된 계획을 순서대로 처리합니다. 상태는 pending, running을 거쳐 completed, partial, failed 중 하나가 됩니다. 전체가 하나의 트랜잭션은 아니므로 뒤 요청이 실패해도 앞서 성공한 요청은 유지됩니다.
권한과 검증
agent.data.read 외에 각 Resource의 읽기 권한이 필요합니다. 쓰기에는 agent.data.write, 해당 Resource 동작 권한, 도구 실행 승인이 모두 필요합니다. SDK Contribution과 App API를 제공하고 Core의 App\Agent\* 클래스를 import하지 마세요.
data.verify는 현재 입력에 대한 사전 검사입니다. 예약이나 권한 토큰이 아니며 실제 실행 때 권한과 입력값을 다시 검사합니다. data.catalog에 나왔더라도 이후 권한이 회수되거나 App을 사용할 수 없게 되면 요청이 거부됩니다.
일반 쓰기 경로로 안전하게 표현할 수 없는 동작은 지원 대상에서 제외하거나 Contribution 계약의 전용 API 도구로 제공하세요. Agent를 위해 기존 컨트롤러의 검증을 약화하지 않습니다.
필드의 설명, 열거값, 번역 키와 참조 의미는 descriptor에 명시하세요. 쓰기에 허용할 값은 요청 검증이 최종 결정합니다. 일반 API가 공개하지 않는 비밀이나 내부 관리 필드는 노출하지 않습니다.
리소스 동작과 전체 탐색
재사용 가능한 동작은 ResourceDescriptor::$actions에 ResourceActionDescriptor로 선언합니다. 정확한 permission, HTTP method, 경로 path, inputSchema를 제공하세요. 동작 키로 권한을 추측하지 않습니다. 예를 들어 reject 동작에 approve 권한이 필요할 수 있습니다. 부수 효과 없는 검사만 ResourceActionEffect::Read로 선언하고 변경은 Mutate를 사용합니다. 선택적인 description에 상태 조건과 업무 의미를 설명하세요. 이 계약은 data.describe로 발견하며 리소스 동작마다 모델 도구를 늘리지 않습니다.
ResourceDescriptor::$mutation에 ResourceMutationDescriptor(createInputSchema: ..., updateInputSchema: ...)를 선언해 중첩 명세를 포함한 전체 입력 계약을 보존합니다. 필드 스키마만으로 쓰기 계약을 대신하지 않습니다. 입력 검증, 권한과 상태 변경은 기존 컨트롤러가 최종 판단합니다.
권한이 있는 리소스를 빠짐없이 순회하려면 data.catalog.next_cursor가 null이 될 때까지 이어서 조회하세요. app.navigation.read는 접근 가능한 설치 앱과 설명을 제공합니다. include_guides로 안내 요약을 보고 guide로 특정 안내의 단계를 조회합니다. 리소스와 메뉴의 참여 조건은 다르며 사용할 수 없는 앱이나 권한 없는 리소스까지 공개하지 않습니다.
범용 리소스 동작으로 표현할 수 없는 고유 업무 기능은 AgentToolContribution으로 제공할 수 있습니다. 중복 list/show/create/update 도구는 등록하지 않습니다. 여러 단계의 업무 안내에는 Feature Guide, 실행 가능한 업무 단계에는 Process Work Action contribution을 사용할 수 있습니다. 안내 자체가 권한을 부여하거나 업무를 실행하지는 않습니다.
동작 확인
생성한 Resource의 필드와 지원 API가 data.describe에 반영되는지 확인하세요. Agent 조회에도 브라우저 API와 같은 읽기 권한이 적용되고, 승인한 수정은 같은 검증과 도메인 동작을 거쳐야 합니다. 권한 회수 후에는 다음 요청이 거부되어야 합니다.
관련 문서
- Resource 만들기 — 모델부터 API까지 생성
- Resource 계약 — 필드와 descriptor 선언
- HTTP 미들웨어 — 테넌트·권한·범위 검사
- 권한과 역할 — Resource별 접근 권한
- Agent Gateway 켜기 — 로컬 Agent 실행