From e48cd7ec8d14f6619c7c1254925d441c8f4f434d Mon Sep 17 00:00:00 2001 From: nalbam Date: Fri, 25 Sep 2026 11:42:03 +0900 Subject: [PATCH] Align Agent Studio skill examples with Agent API --- docs/audio-agent.md | 2 +- docs/code-review-agent.md | 8 ++++---- docs/prompts/audio-agent.md | 4 ++-- plugins/workspace/skills/audio-processing/SKILL.md | 6 +++--- .../skills/audio-processing/references/agent-studio.md | 8 ++++---- .../workspace/skills/audio-processing/references/plaud.md | 4 ++-- plugins/workspace/skills/meeting-minutes/agent-setup.md | 6 +++--- 7 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/audio-agent.md b/docs/audio-agent.md index 16c293a..33a8910 100644 --- a/docs/audio-agent.md +++ b/docs/audio-agent.md @@ -9,7 +9,7 @@ Plaud 녹음의 원본 보관·전사·요약을 하나의 Agent와 AudioJob wor - Agent의 오디오 처리 도구, Plaud MCP 연결과 `get_file`의 source_ref 매핑. - Models에 등록된 **transcription** 모델과 실제로 접근 가능한 provider endpoint·credential. 채팅 모델 등록이나 과거 AudioJob 성공 이력만으로 현재 전사 모델의 준비를 판단하지 않는다. -- 프로젝트 AudioJob config의 전사 모델·언어·보존 기간·동시 접수 한도와 후처리 projectName. +- Agent AudioJob config의 전사 모델·언어·보존 기간·동시 접수 한도와 후처리 agentName. 후처리는 같은 Agent의 현재 설정을 사용하며 versionName을 전달하지 않는다. - 비공개 파일 저장소와 audio-worker. EKS의 S3·Pod Identity와 k3s의 MinIO 연결은 각 설치 설정이다. diff --git a/docs/code-review-agent.md b/docs/code-review-agent.md index 1748098..aa176d6 100644 --- a/docs/code-review-agent.md +++ b/docs/code-review-agent.md @@ -1,12 +1,12 @@ # PR 자동 리뷰 Agent [code-review-agent.md](prompts/code-review-agent.md) 프롬프트와 `code-review` Skill을 연결한다. -프로젝트의 Webhook 동작에서 GitHub PR 리뷰를 선택하고 설치의 GitHub 계정이 접근 가능한 +Agent의 Webhook 동작에서 GitHub PR 리뷰를 선택하고 설치의 GitHub 계정이 접근 가능한 저장소 전체 또는 명시적 `owner/repo` 목록을 설정한다. 공유 GitHub 연결로 댓글을 쓰는 -설정이므로 관리자가 활성화한다. 기본 프로젝트 공개 범위는 검토 자료의 접근 범위에 맞춘다. +설정이므로 관리자가 활성화한다. 기본 Agent 공개 범위는 검토 자료의 접근 범위에 맞춘다. -GitHub 저장소에서 Payload URL을 `/api/webhook/{project}`로, Content type을 -`application/json`으로 지정하고 해당 프로젝트 Webhook Secret과 Pull requests 이벤트를 +GitHub 저장소에서 Payload URL을 `/api/webhook/{agent}`로, Content type을 +`application/json`으로 지정하고 해당 Agent Webhook Secret과 Pull requests 이벤트를 등록한다. 시크릿은 저장소 파일·Agent 프롬프트·PR·로그에 넣지 않는다. 저장소를 읽을 수 있어도 Pull requests 쓰기 권한이 없으면 댓글 게시가 실패한다. diff --git a/docs/prompts/audio-agent.md b/docs/prompts/audio-agent.md index 952942a..c057986 100644 --- a/docs/prompts/audio-agent.md +++ b/docs/prompts/audio-agent.md @@ -1,6 +1,6 @@ -Plaud 녹음을 사용자가 지정한 범위로 가져와 비공개 Artifact에 보관하고, 프로젝트에 설정된 전사 모델과 후처리 Agent로 전사·요약하는 오디오 도우미다. 한국어 존댓말로 실제 결과부터 간결하게 보고한다. +Plaud 녹음을 사용자가 지정한 범위로 가져와 비공개 Artifact에 보관하고, Agent에 설정된 전사 모델과 후처리 Agent로 전사·요약하는 오디오 도우미다. 한국어 존댓말로 실제 결과부터 간결하게 보고한다. -먼저 연결된 audio-processing Skill과 요청에 필요한 참조를 읽는다. 외부 녹음의 ID·제목·기간·시간대와 기존 AudioJob을 확인하고 같은 녹음의 진행 작업이나 현재 파일을 사용할 수 있는 완료 결과를 재사용한다. completed는 처리 이력이며 삭제·만료된 파일의 사용 가능 여부와 다르다. 과거 작업을 재사용하면 원래 완료 시각과 모델을 밝힌다. 프로젝트 AudioJob config의 모델·보존 기간·후처리·접수 한도를 따른다. 필요한 설정이나 연결이 없으면 정확한 막힘을 알리며 모델·ID·URL을 만들어 넣지 않는다. +먼저 연결된 audio-processing Skill과 요청에 필요한 참조를 읽는다. 외부 녹음의 ID·제목·기간·시간대와 기존 AudioJob을 확인하고 같은 녹음의 진행 작업이나 현재 파일을 사용할 수 있는 완료 결과를 재사용한다. completed는 처리 이력이며 삭제·만료된 파일의 사용 가능 여부와 다르다. 과거 작업을 재사용하면 원래 완료 시각과 모델을 밝힌다. Agent AudioJob config의 모델·보존 기간·후처리·접수 한도를 따른다. 필요한 설정이나 연결이 없으면 정확한 막힘을 알리며 모델·ID·URL을 만들어 넣지 않는다. Plaud get_file이 반환한 source_ref를 사용해 AudioJob submit으로 원본 보관 → 전사 → 요약을 접수한다. source_ref와 외부 녹음 ID는 다르다. 사용자의 기간·복수 녹음 요청을 최신 1건으로 축소하지 않는다. 확인한 범위와 접수 한도 때문에 남은 대상을 구별한다. 접수한 job ID와 실제 상태를 보고하고 사용 가능한 원본·전사·요약 Artifact만 안내한다. 링크는 도구가 반환한 artifactLinks를 사용하며 artifact: 또는 sandbox: 경로를 만들지 않는다. 접수 성공을 전사·요약 완료로 표현하지 않는다. diff --git a/plugins/workspace/skills/audio-processing/SKILL.md b/plugins/workspace/skills/audio-processing/SKILL.md index 9ebaaeb..8e11ee6 100644 --- a/plugins/workspace/skills/audio-processing/SKILL.md +++ b/plugins/workspace/skills/audio-processing/SKILL.md @@ -11,7 +11,7 @@ compatibility: > # 오디오 처리 한 Agent가 제공된 도구로 처리한다. 다운로드·전사·요약·기록 때문에 별도 Agent를 만들지 않는다. -긴 처리는 worker에 맡기고 job ID로 이어간다. 모델·출처·보존 기간은 사용자 요청과 프로젝트 설정을 따른다. +긴 처리는 worker에 맡기고 job ID로 이어간다. 모델·출처·보존 기간은 사용자 요청과 Agent 설정을 따른다. ## 입력에 따라 시작한다 @@ -31,7 +31,7 @@ compatibility: > 단일 최신 녹음 요청에서 개수가 없으면 1건만 선택한다. 기간을 지정한 복수 녹음 요청은 범위 안의 후보를 확인한다. 연결된 출처가 Plaud이면 [Plaud 조회](references/plaud.md)를 읽는다. 요청 범위를 임의로 넓히지 않는다. 2. `AudioJob list`로 기존 작업을 확인한다. 같은 녹음의 진행 중인 작업은 재접수하지 않는다. - 새 녹음은 프로젝트의 대기·진행 한도가 남아 있으면 큐에 넣을 수 있다. 실패·차단 작업은 원인을 보고한다. + 새 녹음은 Agent의 대기·진행 한도가 남아 있으면 큐에 넣을 수 있다. 실패·차단 작업은 원인을 보고한다. 반복 polling이나 새 revision으로 우회하지 않는다. 3. 완료된 작업의 task·sourceIdentity·artifacts 관계와 현재 파일 사용 가능 여부를 확인한다. completed는 처리 이력이며 파일이 남아 있다는 뜻이 아니다. 삭제·만료된 결과는 재사용할 수 없다고 보고한다. @@ -44,7 +44,7 @@ compatibility: > 5. 확인한 config의 revision으로 접수한다. 자동 실행에서는 destination이 없어야 한다. 다운로드·전사·요약 요청은 별도 ImportFile로 시작하지 않는다. 녹음마다 `AudioJob submit`으로 제출하면 worker가 보관 → 전사 → 후처리를 이어간다. - 여러 후보는 설정의 maxActive(대기+진행)·maxPerOccurrence를 따라 각각 접수하고 worker가 프로젝트별로 한 건씩 처리한다. + 여러 후보는 설정의 maxActive(대기+진행)·maxPerOccurrence를 따라 각각 접수하고 worker가 Agent별로 한 건씩 처리한다. 한도로 남은 후보는 접수하지 않은 것으로 보고하며, worker가 미접수 후보까지 이어 처리한다고 약속하지 않는다. 정기 실행은 다음 발생에서 같은 기간을 다시 조회하고 완료된 ID를 제외한다. 6. 제출 응답의 status는 접수 결과이고 job.status는 실행 상태다. job.status가 completed이면 diff --git a/plugins/workspace/skills/audio-processing/references/agent-studio.md b/plugins/workspace/skills/audio-processing/references/agent-studio.md index b2eb5d7..ece5565 100644 --- a/plugins/workspace/skills/audio-processing/references/agent-studio.md +++ b/plugins/workspace/skills/audio-processing/references/agent-studio.md @@ -7,7 +7,7 @@ ## 짧은 사용자 요청으로 시작한다 "Plaud 최신 녹음을 전사하고 요약해 줘"처럼 대상과 결과만 받아도 아래 절차를 수행한다. -스킬이 처리 순서를, MCP가 실제 출처 조회를, 프로젝트 설정이 모델·후처리·보존 기간을 담당한다. +스킬이 처리 순서를, MCP가 실제 출처 조회를, Agent 설정이 모델·후처리·보존 기간을 담당한다. ```json {"request":{"operation":"list","cursor":null,"limit":20}} @@ -25,7 +25,7 @@ enabled·revision·model·retention·postprocess를 확인한다. 설정이 없 연결된 출처 MCP에서 목록과 상세를 조회한다. source_ref는 서버가 발급한 참조이며 외부 파일 ID나 URL이 아니다. Plaud plugin의 기본 파일 매핑이 적용되면 get_file 응답에서 source_ref를 받는다. 복수 녹음은 maxActive(대기+진행)와 maxPerOccurrence가 허용하는 만큼 각각 submit한다. -worker는 프로젝트별 접수 순서대로 한 건씩 실행하므로 처리 완료를 기다렸다가 다음 녹음을 제출할 필요가 없다. +worker는 Agent별 접수 순서대로 한 건씩 실행하므로 처리 완료를 기다렸다가 다음 녹음을 제출할 필요가 없다. 접수 한도를 바꾸거나 우회하지 않는다. 한도가 1이면 한 건만 접수하고 나머지는 미접수로 보고한다. ## 새 녹음은 통합 작업 하나로 처리한다 @@ -55,11 +55,11 @@ source는 `{kind:"artifact"|"file"|"source",id:"<해당 참조>"}`이며 languag 이미 전사된 Artifact는 AudioJob postprocess로 요약한다. 오디오 입력으로 다시 제출하지 않는다. ```json -{"request":{"operation":"postprocess","artifact_id":"<전사 Artifact ID>","postprocess":{"projectName":"<후처리 Agent>"},"retention":{"unit":"months","value":3,"timezone":"Asia/Seoul"},"processing_revision":null}} +{"request":{"operation":"postprocess","artifact_id":"<전사 Artifact ID>","postprocess":{"agentName":"<후처리 Agent>"},"retention":{"unit":"months","value":3,"timezone":"Asia/Seoul"},"processing_revision":null}} ``` 후처리 대상과 retention은 실제 config의 값을 사용한다. 별도 Agent를 만들 필요는 없다. -postprocess에는 projectName만 전달한다. 현재 Agent 설정을 사용하므로 versionName을 추가하지 않는다. +postprocess에는 agentName만 전달한다. 현재 Agent 설정을 사용하므로 versionName을 추가하지 않는다. config_revision·전사 model·language·destination은 이 형태에 없다. 설정 대신 명시적 처리 옵션이 필요한 경우에만 operation process를 사용하고 해당 schema를 따른다. diff --git a/plugins/workspace/skills/audio-processing/references/plaud.md b/plugins/workspace/skills/audio-processing/references/plaud.md index cb40497..750a1b3 100644 --- a/plugins/workspace/skills/audio-processing/references/plaud.md +++ b/plugins/workspace/skills/audio-processing/references/plaud.md @@ -6,7 +6,7 @@ Plaud가 실제 녹음 출처이고 해당 MCP가 제공되는 경우에만 사 ## 요청 범위와 목록 - "최근 일주일 녹음을 가져와서 전사하고 요약해"는 실행 시각 기준 최근 7일의 녹음을 조회하고 - 기존 완료 결과를 재사용하며 미처리 녹음을 프로젝트 설정으로 접수하는 요청이다. + 기존 완료 결과를 재사용하며 미처리 녹음을 Agent 설정으로 접수하는 요청이다. 적용한 기간과 시간대를 결과에 밝힌다. 없는 시간대를 추정해 정확한 시각으로 단정하지 않는다. - `list_files`의 실제 schema를 사용한다. `date_from`·`date_to`는 `YYYY-MM-DD`, `query`는 이름 검색이다. 필터가 있으면 pagination이 무시되므로 page만 증가시켜 새 후보를 얻었다고 가정하지 않는다. @@ -17,7 +17,7 @@ Plaud가 실제 녹음 출처이고 해당 MCP가 제공되는 경우에만 사 요청 기간까지 탐색하지 못한 결과일 수 있다. 도구 오류와 빈 목록은 구분한다. - 기존 `AudioJob list`의 `sourceIdentity.itemId`로 같은 녹음의 작업을 찾는다. 완료된 process 작업은 재사용하며 import·transcribe만 끝났으면 필요한 후속 단계만 수행한다. - 기간 내 여러 후보가 있어도 프로젝트의 작업 한도를 바꾸거나 우회하지 않는다. + 기간 내 여러 후보가 있어도 Agent의 작업 한도를 바꾸거나 우회하지 않는다. ## 파일 참조와 접수 diff --git a/plugins/workspace/skills/meeting-minutes/agent-setup.md b/plugins/workspace/skills/meeting-minutes/agent-setup.md index eb3063f..4e4f751 100644 --- a/plugins/workspace/skills/meeting-minutes/agent-setup.md +++ b/plugins/workspace/skills/meeting-minutes/agent-setup.md @@ -3,11 +3,11 @@ 호스트 앱의 비공개 파일 저장소와 audio worker를 설정한다. 운영 Agent는 하나면 된다. - Agent에 `audio-processing`, `meeting-minutes` skill과 오디오 도구를 연결한다. -- 실제 출처 MCP를 같은 Agent에 연결하고 해당 프로젝트에서 인증한다. +- 실제 출처 MCP를 같은 Agent에 연결하고 해당 Agent에서 인증한다. Plaud plugin 기본 파일 매핑이 적용되어 source_ref가 제공되는지 확인한다. 별도 매핑은 기본 응답 형식과 다른 서버에만 설정한다. - 사용자 요청 시 개인 기록도 수행하려면 `personal-records` skill과 설치의 Agent Memory MCP를 같은 Agent에 연결한다. -- 프로젝트 오디오 설정에 Transcription 모델·언어·retention을 지정한다. - postprocess에는 이 Agent의 projectName만 지정하고 destination은 지정하지 않는다. 현재 Agent 설정으로 후처리한다. +- Agent 오디오 설정에 Transcription 모델·언어·retention을 지정한다. + postprocess에는 이 Agent의 agentName만 지정하고 destination은 지정하지 않는다. 현재 Agent 설정으로 후처리한다. 작업 접수 시 실제 버전이 고정되므로 새 배포가 진행 중인 작업을 바꾸지 않는다. - 시간별 처리는 schedule과 소유자의 개인 실행 문맥을 설정한다. 시작 범위·탐색 한도는 schedule 메시지에 둔다. - subagent 연결은 필요하지 않다. worker는 같은 Agent 설정으로 후처리를 실행하고,