지시문과 설명

에이전트에는 사람이 보는 값과 실행에 쓰이는 값이 따로 있다.

이름과 설명은 목록과 상세 화면에서 에이전트를 알아보게 하는 값이다. 모델에는 전달되지 않는다. 에이전트가 어떻게 일할지는 저장소의 AGENTS.md나 CLAUDE.md에 적는다.

일하는 방식은 저장소 파일에 적는다제목 링크 복사

에이전트에게 일하는 방식, 답하는 말투, 지켜야 할 규칙을 알려 주는 방법은 하나다. 세션이 일하는 저장소의 루트에 AGENTS.md(없으면 CLAUDE.md)를 두는 것이다. 카드에는 그런 글을 넣는 칸이 없다.

• 파일은 저장소에 커밋한다. 세션이 시작될 때 커밋된 내용을 읽으므로, 파일을 고치면 새 세션부터 바뀐다. version이나 release를 만들 필요가 없다.
• 프로필이 project_settings.claude_md: true일 때만 읽는다. 꺼져 있으면 파일이 있어도 모델에게 전달되지 않는다. 설정은 프로필 상세의 "저장소의 CLAUDE.md 읽기"에서 켠다. 로컬 프로필 claude-coding-local은 켜져 있다.
• 세션은 시작한 저장소의 파일을 읽는다. 저장소가 다른 에이전트가 같은 파일을 공유한다.

쓰는 법제목 링크 복사

에이전트의 역할은 만든 사람이 정한다. 플랫폼은 역할이나 성격을 정하는 문장을 넣지 않고, 플랫폼만 아는 사실만 전한다. 그 내용은 지금 모델이 읽는 것에 있다.

• 연차나 과장된 수식을 쓰지 않는다. "30년 차 최고의 시니어 개발자" 같은 말은 무슨 일을 맡는지 알려 주지 않는다.
• 담당 범위는 한 줄로 쓴다.
• 허용할 행동은 구체적인 동사로 쓰고 이유를 붙인다. 이유가 있으면 적어 두지 않은 상황에서도 같은 기준으로 판단할 수 있다.

결제 장애 분석을 맡는다.
로그를 읽고 원인을 요약한다.
변경은 담당 팀이 검토하므로 코드는 고치지 않는다.

이전 카드의 값제목 링크 복사

예전 카드에는 "역할"(role)과 "지시 사항"(instructions) 칸, 그 뒤에는 "에이전트 지시문"(agent_instructions) 칸이 있었다. 앞의 두 값은 모델에 전달된 적이 없고, 에이전트 지시문 칸은 없앴다.

• 새로 만드는 카드는 이 값들을 보내지 않는다. 이미 저장된 version의 값은 그대로 남지만 화면에 보이지 않고 실행에도 쓰이지 않는다.
• 옛 클라이언트가 agent_instructions를 보내도 요청은 거절되지 않는다. 그 키는 버려지고 저장되지 않는다.
• 이전에 에이전트 지시문에 적어 둔 내용을 계속 쓰려면 저장소의 AGENTS.md나 CLAUDE.md로 옮긴다.

카드 필드제목 링크 복사

이름(1자부터 120자까지)과 설명(2,000자까지)은 카드가 아니라 에이전트의 필드다. POST /v1/agents와 PATCH /v1/agents/{id}에 name·description으로 보낸다.

웹 콘솔에서 도구 고르기제목 링크 복사

카드 편집(새 에이전트의 "하는 일" 단계, 에이전트 상세의 상세 설정 편집)의 "쓸 수 있는 도구"는 프로필 하나의 도구 체크 목록이다.

• "도구를 보여 줄 프로필": 카드 모델을 돌리는 프로필 중 하나를 고른다. 새 에이전트 흐름은 저장소 없이 release할 수 있는 프로필을 먼저 두고, 고른 프로필을 release 단계에서 먼저 골라 둔다. 이 값은 카드에 저장하지 않는다.
• "릴리스할 때 프로필이 막지 않은 도구 전부"를 켜 두면 tools: null이다. 끄면 체크한 도구가 tools다. 체크를 끄는 것이 금지다.
• 체크를 끈 내장 도구의 tool_policy.per_tool 항목은 저장할 때 지운다. release가 실행하지 않는 내장 도구의 정책을 거절하기 때문이다. MCP 도구 정책은 남는다.
• tools에 프로필에 없는 이름이 있으면 "프로필에 없는 도구"로 체크된 채 보이고, 끌 수만 있다.
• 목록 아래에 고른 도구를 모두 허용하는 프로필 수가 나온다. 0이면 저장할 수 없다.
• 기존 카드에 forbidden이 있으면 목록으로 보이고 "금지 도구 지우기"로 비울 수 있다. 비우기 전에는 체크 목록의 그 도구가 꺼진 채 바꿀 수 없다.

지금 모델이 읽는 것제목 링크 복사

worker가 모델의 시스템 프롬프트에 덧붙이는 지시는 이 순서다.

1. 저장소 없는 세션이면, out/이 체크포인트가 성과물로 모으는 디렉터리라는 사실 한 줄.
2. 저장소 루트의 AGENTS.md. 없으면 CLAUDE.md. 프로필이 project_settings.claude_md: true일 때 커밋된 내용을 읽는다. CLAUDE.md가 AGENTS.md로 가는 링크이거나 @AGENTS.md 한 줄이면 한 번만 읽는다. 로컬 프로필 claude-coding-local은 켜져 있다.

1번의 글은 작업 공간 루트에도 AGENTS.md로 놓이고, CLAUDE.md는 그 파일로 가는 링크다. 둘 다 .git/info/exclude에 올라가 커밋에 섞이지 않는다. 저장소가 AGENTS.md나 CLAUDE.md를 이미 가지고 있으면 덮어쓰지 않는다. 그때도 모델은 같은 글을 시스템 프롬프트로 받는다.

플랫폼은 이 밖의 문단을 모델에 덧붙이지 않는다. 역할이나 행동을 정하는 문장은 플랫폼이 쓰지 않고, 사실만 전한다. 예전 빌드가 붙이던 플랫폼 문단은 없어졌다. 그 문단으로 만든 체크포인트의 지문은 worker가 계속 알아보므로, 이미 있던 세션도 그대로 재개된다.

고치기와 version제목 링크 복사

카드를 보내면 PATCH /v1/agents/{id}가 새 version을 더한다. 이름이나 설명만 바꿀 때는 name·description만 보낸다. 이때는 version이 생기지 않는다. 이미 있는 version과 같은 카드를 보내면 아무것도 더하지 않는다. 만들기의 AID와 WEB을 이어 쓴다.

curl -sS -X PATCH "$API/v1/agents/$AID" "${WEB[@]}" -d '{
  "description": "저장소를 읽고 질문에 답한다",
  "card": {
    "model": "claude-sonnet-5",
    "language": "en",
    "capabilities": { "tools": ["Read", "Grep", "Glob"], "mcp": null },
    "rules": [{ "id": "no-guess", "text": "Never invent a file path.", "source": "user" }]
  }
}' | jq -c '.versions[] | {version_no, language: .card.language}'

{"version_no":1,"language":"follow-user"}
{"version_no":2,"language":"en"}

새 version은 활성 release를 바꾸지 않는다. 쓰려면 그 version으로 release를 만들고 활성화한다(만들기). 웹 콘솔에서는 상세 설정의 "저장"이 같은 일을 하고, 두 version의 차이를 보여 준다.

다음 단계제목 링크 복사

• 프로필 고르기: release와 세션이 쓰는 프로필
• 권한: 도구 권한과 에이전트 관리자