에이전트 / 직접 만든 에이전트
에이전트 / ai-sdk
직접 만든 에이전트
앱 안의 에이전트에 CMS 도구를 줘요. 같은 프로세스에서, 또는 다른 서비스에서. 패키지는 모델을 부르지 않아요.
note
이 페이지는 전에 "AI SDK 도구"였어요. ./ai 입구(cmsTools, remoteCmsTools)는 0.8.0에서 없어졌어요. agent-cms는 에이전트에게 도구만 건네고, 모델 라이브러리에 의존하지 않아요. 대신 쓰는 방법이 아래에 있고, 바꾸는 법은 0.8로 올리기에 있어요.
같은 프로세스에서#
toolsFor(cms, actor)는 이 actor가 쓸 수 있는 도구를 줘요. 이름, 설명, 입력의 zod 스키마예요. callTool은 도구 하나를 실행해요. 쓰는 에이전트 프레임워크의 도구 모양으로 감싸면 돼요.
import { toolsFor, callTool } from "@mainsoft/agent-cms/tools";
const actor = { kind: "system", label: "assistant" } as const;
const tools = toolsFor(cms, actor).map((t) => ({
name: t.name,
description: t.description,
input: t.input, // a zod object; toJsonSchema(t.input) from ./mcp gives JSON Schema
run: (args: unknown) => callTool(cms, actor, t.name, args),
}));callTool(cms, actor, name, args, { only })는 입력을 확인하고, actor의 권한으로 도구를 실행하고, 에이전트가 한 호출로 기록해요. toolsFor(cms, actor, only)와 only 옵션으로 목록을 줄일 수 있어요.
다른 서비스에서#
스크립트, 예약 작업, 다른 서비스는 키를 써요.
import { createCmsClient } from "@mainsoft/agent-cms/client";
import { toolErrorResult } from "@mainsoft/agent-cms/tools";
const api = createCmsClient({ url: "https://app.example.com/api/cms", key: process.env.AGENT_CMS_KEY! });
const tools = await api.listTools(); // only what this key may use: { name, description, inputSchema }
const run = (name: string, args: Record<string, unknown>) =>
api.call(name, args).catch((e) => toolErrorResult(e) ?? Promise.reject(e));listTools()는 그 키가 쓸 수 있는 도구를 서버에 먼저 물어봐요. 읽기 전용 키에는 읽기 도구만 보여요.
로그인한 사람을 대신할 때#
에이전트가 로그인한 사람의 권한으로 일하면 actor에 표시하세요.
await callTool(cms, { ...user, agent: { label: "assistant" } }, "patch_document", args);권한은 그 사람과 똑같아요. 버전, 문서, 감사 로그에 에이전트 이름도 함께 남고, 고친 내용은 "에이전트 변경"에 떠서 검토할 수 있고, 어드민에는 "assistant, Kim"처럼 보여요. CMS를 같은 프로세스에서 부르는 코드만 이렇게 할 수 있어요. REST와 MCP는 받지 않아요.
오류도 결과예요#
도구 오류는 던져지지 않고 결과로 돌아와요. 모델이 다시 읽고 다시 시도할 수 있어요. { error: "conflict_version", kind: "conflict", message, params: { expected, current } } 모양이에요. 모든 코드는 오류 페이지에 있어요.
도구 목록#
- read:
list_collections,search_documents,read_for_answer,list_documents,get_document - write:
create_document,update_document,patch_document,diagnose_document,list_versions,restore_version - publish:
publish_document,unpublish_document,archive_document,delete_document,bulk_documents - 미디어 라이브러리가 있을 때:
list_assets,get_asset(read),import_asset,update_asset(write),move_asset,delete_asset(publish) - 파일 관리자와 함께:
list_store_files(read),register_asset(write),create_share_link(publish)
같은 목록이 MCP로도 나가요. 코딩 에이전트와 앱 안의 에이전트가 같은 도구를 봐요. 문서로 질문에 답하는 방법은 답변하기를 보세요.