AndreasInk/AgentAlertsSkill

에이전트 알림 설정

자동화를 설계하고, 호스팅된 웹훅을 구성하며, 런타임 전송은 $agent-alerts-execution에 맡깁니다. 사용자가 연기 테스트를 요청하지 않는 한, 설정 중에는 전송하지 마십시오.

시작하기

사용자를 다음 페이지로 열거나 안내하십시오:

https://www.andreas.ink/agent

해당 페이지의 현재 연결 흐름을 따라 iPhone의 Agent Alerts와 연결합니다. 런타임용 게시 전용 토큰을 생성합니다. 사용자에게 해당 토큰을 채팅에 붙여넣도록 요청하지 마십시오.

웹훅 구성하기

1. 공개 설정 페이지에서 런타임 이름을 지정하고 연결 흐름을 완료합니다.
2. 런타임에 대한 토큰 위치를 선택합니다:
   • 호스팅된 런타임: 일회용 토큰을 해당 런타임의 비밀 관리자에 AGENTALERTS_AGENT_TOKEN으로 저장합니다.
   • 로컬 Mac: 사용자가 승인한 ~/.config/agent-alerts/token.env 파일에 정확히 한 줄, AGENTALERTS_AGENT_TOKEN=<token>을 저장하고 파일 모드를 0600으로 설정합니다.
3. 사용자가 AI 대화 외부에서 선택한 비밀 저장소에 토큰을 직접 입력하도록 합니다. 절대 에이전트 채팅에 붙여넣도록 요청하지 마십시오.
4. ../agent-alerts-execution/scripts/send_webhook.sh에 내장된 엔드포인트를 사용합니다. 설정 페이지에서 다른 HTTPS 엔드포인트를 제공하는 경우에만 AGENTALERTS_WEBHOOK_URL을 설정합니다.
5. 해당 엔드포인트로만 아웃바운드 HTTPS를 허용합니다.
6. 무인 실행을 위해 send_webhook.sh의 정확한 절대 경로를 승인합니다. 광범위한 셸 액세스를 부여하지 마십시오.

토큰을 프롬프트, URL, 쿼리 문자열, 로그, 소스 파일, 추적된 설정 파일, 셸 기록 또는 명령 인수에 절대 넣지 마십시오.

테스트 준비 및 검증

../agent-alerts-execution/assets/compact-webhook-payload.json을 쓰기 가능한 페이로드 파일로 복사하고 예제 값을 바꿉니다. 이벤트에 대해 안정적이고 고유한 idempotency 키를 사용합니다.

페이로드를 검증하십시오:

../agent-alerts-execution/scripts/send_webhook.sh --check payload.json

전송하지 않고 페이로드, 토큰 소스, 권한 및 엔드포인트를 검증하십시오:

../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json

그런 다음 민감하지 않은 연기 테스트를 한 번 전송하십시오:

../agent-alerts-execution/scripts/send_webhook.sh payload.json

무인 자동화의 경우, 실제 저장된 실행기에서 --check-config와 연기 전송을 반복하십시오. 둘 다 승인 프롬프트 없이 완료되어야 합니다. 실행기가 정확한 헬퍼를 실행하거나 엔드포인트에 도달할 수 없는 경우, AGENTALERTS_SCRIPT_NOT_AUTHORIZED와 함께 중지하십시오.

알림 설계하기

정의:

1. 신호, 데이터 소스 및 트리거.
2. good, warning 및 critical 매핑.
3. 건너뛰기 조건, 방해 금지 시간 및 제외 사항.
4. 안정적인 activity_id 또는 알림 식별자.
5. 표면: live_activity, widget 및/또는 notification.
6. 작업 텍스트와 안전한 대상 URL 또는 앱 딥 링크.
7. 알림이 나중에 또는 반복적으로 실행될 경우 내구성 있는 스케줄러.

Agent Alerts는 업데이트를 전달합니다. 에이전트 세션을 활성 상태로 유지하지 않습니다. 예약된 실행이 현재 세션이 종료된 후에도 스케줄러가 등록된 상태로 유지되지 않으면 불완전합니다. 그렇지 않으면 AGENTALERTS_SCHEDULER_NOT_DURABLE을 반환하십시오.

페이로드 계약

일반 알림에는 간결한 웹훅 본문을 사용하십시오:

{
  "title": "빌드 완료",
  "summary": "모든 테스트 통과.",
  "status": "good",
  "activity_id": "build-monitor",
  "source_name": "Codex",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}

웹훅에는 다음이 필요합니다:

Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <idempotency_key와 동일한 값>

헬퍼는 프로세스 인수에 토큰을 노출하지 않고 이러한 헤더를 제공합니다. 항상 헬퍼를 사용하십시오. 수동으로 요청을 다시 생성하지 마십시오.

간결한 전송은 기본적으로 webhook이라는 이름의 활동 하나를 upsert하고, 프로덕션 전달을 수행하며, 해당 필드가 생략된 경우 live_activity와 notification을 포함합니다. 자동화에 다른 결과가 필요한 경우 명시적으로 설정하십시오.

위젯, 제어 위젯 상태, 빌더 레이아웃 또는 기타 고급 필드의 경우, 중첩된 payload 객체와 함께 웹훅의 전체 스네이크 케이스 계약을 사용하십시오. 전체 payload 객체를 간결한 title, summary, status, source_name 또는 deep_link 필드와 혼합하지 마십시오.

표시 및 전달 규칙

표시되는 텍스트는 완전해야 하며 다음 한도 내에 있어야 합니다:

필드	최대 문자 수
source_name	14
title	32
summary	96

잘림에 의존하거나 줄임표를 추가하지 마십시오.

• live_activity는 다이내믹 아일랜드 또는 잠금 화면을 업데이트합니다.
• widget은 위젯 식별자, 작은 비밀 아닌 스냅샷 및 다시 로드 활성화가 필요합니다.
• notification은 그룹화를 위한 안정적인 스레드 식별자가 필요합니다.
• 제어 위젯 상태는 활성 경고 또는 위험 상태의 경우 true여야 하고, 해결 또는 지워진 상태의 경우 false여야 합니다.

런타임 핸드오프

정확한 런타임 명령어 하나를 작성하십시오:

$agent-alerts-execution을 사용하십시오. 먼저 구성된 건너뛰기 조건을 평가하십시오. 전송이 필요한 경우, 준비된 Agent Alerts JSON을 승인된 페이로드 경로에 쓰고, 승인된 절대 send_webhook.sh 경로를 해당 파일과 함께 호출하십시오. 토큰은 AGENTALERTS_AGENT_TOKEN 또는 승인된 token.env 파일에서만 읽으십시오. 반환된 상태와 대상, 성공 및 실패 횟수를 비밀을 출력하지 않고 보고하십시오.

실제 실행기가 상호 작용 없이 구성을 검증하고 전송하며, 필요한 경우 스케줄이 내구성 있고, 결과가 장치에 표시되는 전달을 과장하지 않고 보고될 때만 설정이 완료됩니다.