에이전트 도구
앱이 AI 에이전트(MCP)에 도구를 제공하고, 에이전트가 관리 API로 그 도구를 부르는 방법
앱은 매니페스트 mcp.tools에 도구를 선언해 상점의 AI 에이전트가 쓸 수 있게 합니다. 에이전트는 원격 MCP의 관리 API
도구로 설치된 앱의 도구를 찾고 부릅니다. 앱 도구는 앱의 설치 토큰으로 실행되므로 상점이 앱에 동의한 권한 안에서만 동작합니다.
{
"handle": "erp-sync",
"name": "ERP 연동",
"scopes": ["order:r", "product:r"],
"mcp": {
"tools": {
"stock-lookup": {
"description": "ERP 창고 재고를 상품 코드로 조회합니다",
"input": {
"sku": { "type": "string", "description": "상품 코드", "required": true },
"warehouse": { "type": "string", "description": "창고 코드" }
}
}
}
}
}| 필드 | 규칙 |
|---|---|
mcp.tools | 이름(소문자·숫자·하이픈 40자) → description(500자)·input. 20개까지 |
input | 이름(영문으로 시작 40자) → type(string · number · boolean)·description·required. 20개까지 |
도구는 동의 화면의 「AI 에이전트 도구」 문단에 이름과 설명이 보이고, 도구가 늘어난 버전은 재동의가 필요합니다.
앱 코드
export default defineApp({
tools: {
"stock-lookup": async (input, ctx) => {
const stock = await fetchErpStock(String(input.sku), ctx.secrets.ERP_KEY);
return { sku: input.sku, quantity: stock.quantity }; // JSON으로 바꿀 수 있는 값
},
},
});- 함수의 반환값이 에이전트에게 그대로 갑니다(JSON, 64KB까지). 예외를 던지면 에이전트는
502 APP_TOOL_FAILED를 받습니다. input은 매니페스트의input선언대로 검사한 뒤 넘어옵니다. 선언하지 않은 키는 버립니다.- 함수가 없는 도구가 매니페스트에 있으면 빌드가
HANDLER_MISSING으로 실패합니다. - 로컬에서는
npx sayren app trigger --tool stock-lookup --data '{"sku":"A-1"}'로 부릅니다.
관리 API
| API | 설명 |
|---|---|
GET /v1/apps/tools | 이 상점에 설치된 앱의 도구 목록(설치 id·앱·이름·설명·입력). store:r |
POST /v1/apps/installations/{installationId}/tools/{name} | 도구 실행. 본문 { "input": { … } }, 응답 { "result": … }. 상점의 소유자·관리자만 |
| 오류 | 뜻 |
|---|---|
404 APP_TOOL_NOT_FOUND | 설치가 없거나 끝났거나, 실행 버전에 그 도구가 없습니다 |
400 APP_TOOL_INPUT_INVALID | 필수 입력이 없거나 형식이 다릅니다 |
502 APP_TOOL_FAILED | 앱 코드가 실패했습니다 |
409 APP_SUSPENDED | 앱이 정지됐습니다 |
에이전트는 list_operations로 이 두 API를 찾고 call_api_read·call_api_write로 부릅니다.