사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
에이전트 UI
화면에 이미 있는 버튼을 같은 가드 아래에서, 사람이 보는 앞에서 눌러 주는 도우미입니다. 로봇용 API를 따로 만드는 것이 아닙니다.
Agent 네임스페이스가 그 UI입니다. 레이아웃에 <Agent.Chat /> 하나면 연결이 끝나고, 나머지 멤버는 범위를 좁히거나 에이전트가 보는 것을 보여 줍니다.import { Agent } from "akanjs/ui";릴레이 엔드포인트는 툴을 실행하지 않습니다. 모든 호출은 사용자 자신의 브라우저 세션에서, 앱의 가드와 승인 카드를 거쳐 실행됩니다. 그래서 툴은 컴포넌트가 선언한 곳에만 있고, 화면이 사용자에게 주지 않은 조작은 에이전트도 할 수 없습니다.
이 페이지에서 쓰는 말
용어설명
툴 (tool)
컴포넌트가
st.tool로 공개한 동작 하나입니다. 보통 버튼이 이미 부르는 핸들러입니다.표면 (surface)
지금 화면에서 에이전트가 실행하고 읽을 수 있는 것 전부, 즉 마운트된 툴과 키입니다.
세션 (session)
루프와 옵션을 가진 대화 하나입니다.
Agent.Chat과 Agent.Zone이 각자 하나씩 만듭니다.대화 기록 (transcript)
지금까지의 대화입니다. 매 턴마다 모델에 다시 전송됩니다.
기본 툴 (builtins)
런타임이 모든 화면에 넣어 주는 툴입니다.
navigate, goBack, readScreen, readState, highlight.리소스 (resource)
컴포넌트가
st.expose나 st.useState로 공개해 에이전트가 읽을 수 있게 한 값입니다.멤버
멤버
자체 UI
자기 대화
이름 접두사
사용자가 대화하는 곳
Agent.Chat
✓
✓
채팅 패널입니다. 런처, 대화창, 입력창, 승인 카드가 들어 있고 한 번만 마운트합니다.
Agent.Zone
✓
✓
개념 설명 문서
이 페이지는 멤버와 props 목록입니다. 그 뒤의 개념은 아래 문서에서 다룹니다.
Chat
사용자가 보는 채팅입니다. 이 화면이 선언한 툴과 상태에 연결된 떠 있는 패널이며, 대화 루프와 모든 툴 호출이 이 브라우저에서 실행됩니다. 레이아웃에 한 번만 마운트합니다.
속성과 API
세션 옵션
대화가 돌아가는 방식이며 마운트할 때 한 번만 읽습니다.
Agent.Zone이나 AgentProvider 안에서는 채팅이 그 세션에 합류하므로, 이 값은 그 세션을 만든 쪽이 정합니다.instructionsstring
앱 전역 지침입니다. 라우트별 지침은 마운트된
Agent.Guide가 그 위에 겹칩니다.runnerAgentRunner기본값 fetchRunner()
전송 방식을 바꿉니다. 기본값은 앱의
runAgentTurn으로 보내고, httpRunner({ url })는 다른 주소로 보냅니다.maxTurnsnumber기본값 12
질문 하나가 쓸 수 있는 모델 왕복 횟수입니다. 한도에 닿으면 계속할지 사용자에게 묻습니다.
compactCompactOptions기본값 { at: 24_000, keep: 6, buffer: 13_000 }
Zone
같은 화면을 좁혀 보는, 자기 대화를 가진 구획입니다. 안에 둔
Agent.Chat은 자동으로 이 zone에 묶이므로, 한 화면의 zone 두 개는 각자 자기 하위 트리만 보면서 대화 두 개를 나란히 돌립니다.속성과 API
idstring
필수입니다. 이름 접두사와
data-agent-zone 값이 여기서 나오며, A-Za-z0-9_- 밖의 문자는 -가 됩니다.childrenReactNode
구획 자체입니다. 여기 마운트된 것은 모두 이 zone에 속합니다.
classNamestring
data-agent-zone이 붙는 감싸는 div에 붙습니다.labelstring
scope의 읽기 쉬운 이름입니다. 화면 컨텍스트와 함께 모델에 전달됩니다.
instructionsstring
Agent.Guide로 마운트되는 zone 지침입니다. 루트 에이전트도 읽고, 형제 zone은 읽지 않습니다.Guide
라우트 하위 트리에 상시 적용되는 지침입니다.
_layout.tsx나 페이지에서 렌더하면 그 트리가 마운트된 동안 매 턴의 지침에 합쳐집니다. 화면에는 아무것도 그리지 않습니다.속성과 API
instructionsstring
지침 문구이며 항상 영어로 씁니다. 모델이 읽는 문자열이라
l() 규칙 대상이 아닙니다.- 렌더 트리가 곧 적용 범위입니다. 마운트된 Guide마다 자기 블록을 더하고, 다른 곳으로 이동하면 빠집니다.
- 라우트 체인의 단계(stage)가 아니라 컴포넌트입니다.
page()에도pageConfig에도instructions필드는 없고,*.abstract.md도 에이전트에게 전달되지 않습니다.
apps/koyo/page/(user)/plan/_layout.tsx
History
감싸고 있는 zone의 대화 기록을 앱이 가진 저장소에 연결합니다.
persist와 같은 일을 prop 대신 마운트하는 컴포넌트로 하며, 화면에는 아무것도 그리지 않습니다.속성과 API
load / save / clearSessionHistory["load" | "save" | "clear"]
저장소의 세 가지 동작입니다. ref로 읽으므로 인라인 함수로 적어도 됩니다.
onCompact(replaced, summary) => void
서버 쪽 요약을 따로 가진 앱이 자기 워터마크를 옮기는 자리입니다.
persist대신 컴포넌트인 이유. 함수는 prop으로 서버/클라이언트 경계를 넘지 못하므로, 세션을 만드는 쪽에persist를 넘기면 그 위의 조상이 모두 클라이언트 컴포넌트가 됩니다. 이 말단 컴포넌트 하나만 클라이언트로 두면 zone과 채팅은 서버 컴포넌트에 남습니다.- 감싸는 세션이 있어야 합니다.
<Agent.Zone id="thread"><ThreadHistory … /></Agent.Zone>처럼Agent.Zone이나AgentProvider안에 마운트합니다. 루트Agent.Chat은 세션을 아래로 내려 주지 않으므로, 그쪽은persist를 씁니다. - 복원은 대화가 비어 있을 때만 일어납니다. zone과 함께 마운트하면 복원되고, 대화에 무언가 일어난 뒤에 마운트하면 그때부터 저장만 합니다.
- 저장소는 이 컴포넌트가 마운트된 동안만 연결됩니다. zone이 만든 세션은 어차피 zone과 함께 끝나지만, 앱이 넘긴 세션은 더 오래 살고 언마운트 시점에 저장이 멈춥니다. 계속 저장하려면
session.setHistory를 직접 호출하세요. 그 호출이 자리를 차지하므로 이후의 언마운트가 건드리지 않습니다.
Skip
기본 화면 읽기에서 빠지는 영역입니다. 푸터, 쿠키 배너, 반복되는 내비게이션처럼 토큰만 쓰고 답에는 도움이 안 되는 부분에 씁니다.
속성과 API
labelstring
읽기 결과에서 영역 대신 찍히는 이름이자
section으로 읽을 때 쓰는 이름입니다. 필수입니다.childrenReactNode
건너뛸 영역 자체입니다.
classNamestring
감싸는
div에 붙습니다.- 에이전트는 무엇을 건너뛰었는지 압니다. 그 자리에
[skipped: <label>]이 남으므로, 푸터를 물으면 푸터가 없다고 하지 않고 읽지 않았다고 답합니다. 필요하면section: "<label>"으로 읽습니다. - 숨기는 것은 글이지 동작이 아닙니다. 툴과 상태 키는 마크업이 아니라 선언이므로, 안에 있는
st.tool도 그대로 공개되고highlight도 안쪽 컨트롤에 닿습니다. - 감싸는 div가 레이아웃을 흔든다면 속성을 씁니다. flex 컨테이너와 자식 사이처럼 div가 끼면 안 되는 곳에서는 이미 그리는 요소에 직접 붙입니다.
<footer data-agent-skip="site footer">
Scope
아래에서 등록되는 툴과 리소스 이름에 접두사를 붙여, 반복되는 목록 항목이 같은 이름을 쓸 수 있게 합니다. 대화를 열지도, 세션을 갖지도 않습니다.
속성과 API
idstring
접두사입니다. 아래의 모든 것이
<id>.<name>으로 공개되고, 중첩된 scope는 점으로 이어집니다.childrenReactNode
접두사가 적용되는 하위 트리입니다.
labelstring
scope의 읽기 쉬운 이름입니다. 화면 컨텍스트와 함께 모델에 전달됩니다.
kindstring
scope의 종류입니다.
Agent.Zone은 kind="zone"으로 자기 scope를 엽니다.- Scope와 Zone 중 무엇을 쓸까? 반복되는 하위 트리에서 툴 이름만 구분하고 에이전트는 화면 하나를 함께 쓰면 될 때
Agent.Scope를 씁니다.Agent.Zone은 scope를 감싸고 자기 대화까지 엽니다.
개발용 도크
에이전트 표면은 컴포넌트마다 따로 선언하므로, 파일 하나만 봐서는 화면 전체가 무엇을 공개했는지 알 수 없습니다.
Agent.Dock이 그것을 보여 줍니다. 개발 중에는 아래처럼 채팅 옆에 마운트합니다.apps/koyo/page/(user)/_layout.tsx
- 프로덕션에서는 그리지 않습니다.
Agent.Dock과Agent.Context는AKAN_PUBLIC_ENV=main에서 아무것도 그리지 않으므로, 마운트해 두어도 방문자에게는 비용이 없습니다. - 나머지 부품은 환경을 확인하지 않습니다.
Agent.Section,Agent.StateKey,Agent.Tool,Agent.Transcript로 직접 만든 인스펙터는 프로덕션에서 스스로 숨겨야 합니다. open은 Tools를 펼칩니다. Transcript는 항상 펼친 채로, 나머지 섹션은 접힌 채로 시작합니다.
섹션별로 확인하는 것
섹션설명
Tools
이 화면이 작성자가 의도한 툴을, 지침에 적힌 이름 그대로 공개했는가?
State