위임과 업무 목표 계약
사람이 에이전트에게 맡긴 일의 범위(작업 · 대상 · 기간 · 수량)를 Contexa에 알려 주는 방법과, Contexa가 그 범위를 실제 요청과 비교해 판정 모델에 사실로 건네는 방식을 설명합니다. 범위를 벗어났다고 엔진이 차단하지는 않습니다. 엔진은 비교만 하고, 판정은 모델이 합니다.
한눈에 보기
- 요청이 밝힌 위임토큰 클레임 · 세션 · 요청 속성 · 헤더에서 읽은 위임 도장
- 위임 기록기록으로 좁히기사람이 남긴 위임 기록(또는 앱의 업무 시스템)으로 범위를 좁힘. 넓히지는 않음
- Contexa범위 비교지금 작업 · 대상 · 건수가 위임 범위와 업무 목표 계약 안인지 비교해 "이탈 예 / 아니오"를 사실로 만듦
- AI 모델판정비교 사실과 다른 맥락을 함께 보고 허용 · 추가 확인 · 차단을 정함
위임 한 건에 담는 것
| 칸 | 뜻 | 예 |
|---|---|---|
agentId | 일을 맡은 에이전트(필수) | report-bot |
objectiveId / objectiveFamily | 맡긴 일의 ID / 일의 종류(앱이 선언한 업무 목표 계열) | RPT-2026-10 / MONTHLY_REPORT |
objectiveSummary | 위임자가 쓴 일 설명(1000자까지). 판정에서는 믿지 않는 글로 따로 다룸 | 10월 매출 보고서 작성 |
allowedOperations | 허용 작업. @Protectable의 actions 이름과 같은 말(대문자로 바뀜) | ["READ"] |
allowedResources | 허용 대상: 경로 패턴 또는 앱의 업무 ID | ["/api/reports/**"] |
approvalRequired | 일하기 전에 위임자의 승인이 필요한지 | false |
privilegedExportAllowed | 특권 데이터 반출을 허용하는지(밝히지 않으면 비움) | false |
containmentOnly | 읽기 · 봉쇄만 하도록 맡겼는지 | false |
validFrom / expiresAt | 시작(기본 지금) / 끝(필수) | 2026-11-30T00:00:00Z |
maxItemsPerRequest / maxItemsTotal | 반출 한 번의 최대 건수 / 세션 누계 최대 건수(1 이상, 밝히지 않으면 없음) | 100 / 1000 |
작업 · 대상 목록은 각각 100개까지입니다. 위임은 만료되거나 철회되면 끝나지만 기록은 남습니다. 끝난 시각 자체가 판정이 따지는 사실이기 때문입니다.
위임을 알려 주는 길
| 길 | 누가 | 어떻게 |
|---|---|---|
| 위임 API | 위임자 본인 | POST /contexa/api/agent-delegations. 로그인한 사람 이름으로만 기록됩니다. |
| 관리 API | 관리자 · 연동 시스템 | POST /contexa/admin/api/agent-delegations(ADMIN 역할). 위임자 · 기록자 · 기록 시각을 앱의 기록대로 넣습니다. |
| 토큰 클레임 | 인가 서버 | delegation_id, objective_*, allowed_*, authorization_details(RFC 9396) 등(클레임 이름) |
| 업무 시스템 조회 | 앱 | DelegationRecordLookup 빈. 위임을 앱의 업무 시스템에 두는 경우의 주된 방법입니다(확장점). |
| 세션 · 요청 속성 · 헤더 | 앱 · 게이트웨이 | 세션 속성, 요청 속성 ctxa.delegation.*, 헤더 X-Contexa-*(기본 꺼짐, 신뢰 프록시 필요) |
act), 에이전트 자기 토큰, 에이전트 계정으로 위임 API를 부르면 403으로 거부합니다.
위임 API
POST /contexa/api/agent-delegations
Content-Type: application/json
{
"agentId": "report-bot",
"objectiveFamily": "MONTHLY_REPORT",
"objectiveSummary": "10월 매출 보고서 작성",
"allowedOperations": ["READ"],
"allowedResources": ["/api/reports/**"],
"expiresAt": "2026-11-30T00:00:00Z",
"maxItemsPerRequest": 100,
"maxItemsTotal": 1000
}
- 성공하면
201과 위임을 돌려줍니다. 응답의state는VALID·NOT_STARTED·EXPIRED·REVOKED중 하나입니다. - 끝 시각은 시작보다 뒤여야 하고, 기간은
contexa.security.zerotrust.agent.delegation-max-validity(기본 30일)를 넘을 수 없습니다. 일이 이어지면 다시 위임합니다. GET은 내 위임을 최신순으로 200개까지,POST /{delegationId}/revoke(본문{"reason": "..."})는 내 위임을 철회합니다. 관리 API의 철회는 이유가 필수입니다.- 한 사람이 같은 에이전트에 여러 위임을 남기면, 요청이
delegation_id로 고른 위임을 쓰고, 없으면 지금 유효한 위임 가운데 가장 늦게 시작한 것, 그것도 없으면 끝난 위임까지 포함해 가장 늦게 시작한 것을 씁니다. - 위임을 기록하거나 철회할 때마다 감사 기록에
AGENT_DELEGATION_RECORDED·AGENT_DELEGATION_REVOKED가 누가 했는지와 함께 남습니다. 위임자의 계정을 지우면 그 사람의 위임도 함께 지웁니다.
위임 기록은 범위를 좁히기만 합니다
토큰 · 세션이 밝힌 위임과 위임 기록이 다르면, Contexa는 항상 더 좁은 쪽을 씁니다. 그래서 토큰을 넓게 받아도 기록이 범위를 묶습니다.
토큰이 밝힌 위임
- 작업 READ, EXPORT
- 대상
/api/** - 끝 18:00
- 건수 한도 없음
위임 기록
- 작업 READ
- 대상
/api/reports/** - 끝 17:00
- 요청당 100건
판정에 쓰는 위임
- 작업 READ
- 대상
/api/reports/** - 끝 17:00
- 요청당 100건
| 항목 | 규칙 |
|---|---|
| 목표 | 다르면 기록의 목표 |
| 허용 작업 · 대상 | 둘 다 말한 항목만. 겹치는 항목이 없으면 기록의 목록(빈 목록은 "밝히지 않음"이라 범위를 넓히게 되므로) |
| 승인 필요 · 봉쇄 전용 | 어느 한쪽이라도 요구하면 요구 |
| 특권 반출 | 둘 다 막지 않을 때만 허용 |
| 끝 시각 · 수량 한도 | 이른 끝, 낮은 한도 |
| 다른 에이전트의 기록 | 적용하지 않음 |
조회 결과는 판정 맥락에 delegationRecordLookup으로 남습니다: FOUND(적용), NOT_FOUND(기록 없음, 요청이 밝힌 위임 그대로), AGENT_MISMATCH(다른 에이전트의 기록), FAILED(조회 실패). 기록이 덮어쓴 항목은 충돌 목록으로, 기록 작성자 · 시각도 함께 남습니다. 사람 본인의 요청은 조회하지 않습니다.
단독 에이전트의 상시 위임
단독 에이전트는 위임자가 없습니다. 이때 Contexa는 등록 책임자(sponsor)가 그 에이전트에 남긴 위임을 한 번 더 찾아 상시 위임으로 같은 규칙을 적용합니다. 책임자가 위임 API로 그 에이전트에 위임을 기록해 두면 됩니다. 에이전트는 여전히 자기 이름으로 일하므로 요청을 "위임됨"으로 표시하지는 않습니다.
업무 목표 계약
앱은 업무 목표 계열마다 그 일에 필요한 작업과 자원 계열을 선언할 수 있습니다. 위임이 허용 작업 · 대상 계열을 밝히지 않았으면 이 계약이 비교 기준이 됩니다.
contexa:
security:
zerotrust:
agent:
objective-contracts:
MONTHLY_REPORT: # 위임의 objectiveFamily와 같은 이름
operations: [READ] # @Protectable의 actions와 같은 말
resource-families: [REPORT] # @Protectable의 category와 같은 말
max-export-items: 500 # 반출 한 번의 최대 건수
- Contexa 자체 보안 목표 계열(감사 · 봉쇄 · 학습 등)은 이미 알고 있고, 앱이 같은 이름을 선언하면 앱의 계약이 대신합니다.
- 코드로 선언하려면
ObjectiveContractSource빈을 둡니다. Contexa 자체 계약 → 설정의 계약 → 소스 빈의 계약 순서로 읽고, 같은 계열은 나중 것이 앞의 것을 대신합니다. - 설정에는
read-only·privileged-export-allowed칸도 있지만, 현재 버전의 범위 비교에는 쓰이지 않습니다. 특권 반출 금지는 위임의privilegedExportAllowed로 비교합니다.
범위 이탈: 엔진은 비교, 판정은 모델
엔진은 요청마다 아래 항목을 비교하고, 결과를 "이탈 예 / 아니오"와 비교 문장으로 판정 맥락에 넣습니다. 비교할 입력이 하나도 없으면 "비교 불완전"으로 남깁니다.
| 비교 | 기준 |
|---|---|
| 지금 작업이 허용 작업에 있나 | 위임의 목록, 없으면 계약의 operations. 작업을 알 수 없으면 비교하지 않음 |
| 지금 자원 계열이 허용 계열에 있나 | 위임의 목록, 없으면 계약의 resource-families |
| 지금 대상이 허용 경로 · 업무 ID에 맞나 | 위임의 allowedResources에 적은 경로 패턴 · ID |
| 봉쇄 전용 위임에서 다른 작업인가 | 읽기 · 조회 · 봉쇄만 범위 안 |
| 반출 건수가 한도 안인가 | 계약의 max-export-items, 위임의 maxItemsPerRequest, 세션 누계와 maxItemsTotal |
| 특권 반출을 막은 위임에서 반출인가 | 위임의 privilegedExportAllowed = false |
- 건수는 앱이 알려 줄 때만 비교합니다. 요청 속성
ctxa.context.requestItems(또는requestItems)에 요청 건수를 넣어 주세요. - 이탈을 이유로 판정을 강제하는 규칙은 없습니다. 모델이 사실을 보고 판정합니다. 모델이 근거로
DELEGATION_SCOPE_DRIFT를 들면, Contexa는 그 사실이 실제로 맥락에 있는지만 검사합니다.
정책 식으로 위임 확인하기
모델 판정과 별도로, URL · 메서드 정책에서 위임을 결정적으로 따질 수 있습니다. 이 식들은 요청의 위임 도장(토큰 · 세션 등)을 읽습니다. 위임 기록으로 좁힌 결과는 모델 판정에 쓰입니다.
| 식 | 뜻 |
|---|---|
isAgent() / isDelegatedAgent() / isAutonomousAgent() | 에이전트 요청인지 / 위임 에이전트인지 / 단독 에이전트인지 |
agentId / isAgentIn('a', 'b') | 요청한 에이전트 ID / 그 가운데 하나인지 |
delegatorId | 위임자(위임 에이전트일 때) |
delegationChainDepth / delegationChainDepthAtMost(n) | 위임 사슬 깊이(사람 · 단독 에이전트 0, 직접 위임 1) / n 이하인지 |
delegationAllowsOperation('READ') | 위임이 그 작업을 허용하는지 |
delegationAllowsResource('/api/reports/1') | 위임이 그 대상을 허용하는지(목록 항목이 *로 끝나면 앞부분이 같은 모든 대상) |
delegationRequiresApproval() | 위임이 위임자 승인을 요구하는지 |
isDelegatedAgent() and delegationAllowsOperation('READ') and delegationChainDepthAtMost(1)
확인 · 호출 수 관련 식(agentRequestConfirmed(), agentCallsInLastMinuteAtMost(n))은 정지 · 확인 · 제한에 있습니다. 식 전체 목록은 AI 보안 표현식을 보세요.
설정
토큰 클레임 이름(contexa.bridge.delegation.token.*)
| 설정 | 기본값 |
|---|---|
enabled | true |
actor-claims / may-act-claims | [act] / [may_act](may_act는 참고로만 기록) |
client-id-claims / agent-id-claims | [azp, client_id, appid] / [agent_id, agentId] |
tenant-claims / delegation-id-claims | [tid, tenant_id] / [delegation_id, delegationId] |
subject-type-claims / user-subject-types | [idtyp, sub_profile] / [user] |
scope-claims / authorization-details-claims | [scope, scp] / [authorization_details] |
objective-id-claims / objective-family-claims / objective-summary-claims | [objective_id, objectiveId] / [objective_family, objectiveFamily] / [task_purpose, objective_summary, objectiveSummary] |
allowed-operations-claims / allowed-resources-claims | [allowed_operations, allowedOperations] / [allowed_resources, allowed_resource_families, allowedResources] |
approval-required-claims / privileged-export-allowed-claims / containment-only-claims | [approval_required, approvalRequired] / [privileged_export_allowed, privilegedExportAllowed] / [containment_only, containmentOnly] |
expires-at-claims | [delegation_expires_at, execution_expires_at, delegationExpiresAt]. 없으면 위임은 토큰 만료보다 늦게 끝나지 않음 |
에이전트 표지(agent-actor-markers, delegated-markers, agent-client-ids)는 에이전트를 알아보는 길에 있습니다. 세션 · 요청 속성 · 헤더에서 읽는 설정(contexa.bridge.delegation.session.* · request-attributes.* · headers.*)은 인증 브리지 설정을 보세요.
그 밖의 설정
| 설정 | 기본값 | 뜻 | 언제 바꾸나 |
|---|---|---|---|
contexa.security.zerotrust.agent.delegation-max-validity | 30d | 위임 API로 기록하는 위임의 최대 기간 | 더 긴 위임(예: 분기 업무)을 허용하거나 더 짧게 묶을 때 |
contexa.security.zerotrust.agent.objective-contracts.<계열>.* | 비어 있음 | 업무 목표 계약 | 앱의 업무 목표를 선언할 때 |
contexa.auth.oauth2.delegation-claim-enabled | true | Contexa 인가 서버의 교환 토큰에 유효한 위임의 delegation_id를 실음(CONTEXA_OWNED) | 교환 토큰에 위임 ID를 싣지 않으려면 false |
확장점
위임을 앱의 업무 시스템에서 읽기
위임을 이미 앱의 결재 · 업무 시스템에 두고 있다면 DelegationRecordLookup 빈 하나로 연결합니다. 빈을 두면 Contexa가 모든 에이전트 요청에 그 기록을 적용합니다.
@Bean
DelegationRecordLookup delegationRecordLookup(WorkOrderRepository workOrders) {
return query -> workOrders
.findActive(query.delegatorId(), query.agentId(), query.requestedAt())
.map(order -> new DelegationRecord(
order.id(), order.requester(), order.agentId(),
order.taskId(), "MONTHLY_REPORT", order.title(),
List.of("READ"), List.of("/api/reports/**"),
false, false, false,
order.dueAt(), order.approver(), order.approvedAt(),
100, 1000));
}
- 분석 스레드에서, 에이전트나 위임을 밝힌 요청마다 한 번 불립니다. 맞는 기록이 없으면
Optional.empty()를 돌려줍니다. 예외는 "조회 실패"로 남고 판정은 요청이 밝힌 위임으로 계속됩니다. - 끝난 위임도 돌려주세요. 끝 시각이 판정이 따지는 사실입니다.
query.standing()이true이면 단독 에이전트의 상시 위임 조회이고,delegatorId는 그 에이전트의 책임자입니다.
| 빈 | 언제 필요한가 | 기본 동작 |
|---|---|---|
DelegationRecordLookup | 위임을 앱 업무 시스템에 둘 때 | Contexa 위임 보관소 조회 |
DelegationRegistry | 위임 보관소를 바꿀 때 | Contexa DB가 있으면 JDBC(ctxa_agent_delegation_record 표), 없으면 메모리 |
DelegationContextProvider(추가) / RecordedDelegationContextProvider(교체) | 위임 사실을 더 붙이거나 좁히기 규칙을 바꿀 때 | 위 좁히기 규칙 |
DelegationStampResolver(추가) | 다른 통로에서 위임을 읽을 때(@Order로 순서) | 토큰 · 세션 · 요청 속성 · 헤더 · 에이전트 계정 5종 |
ObjectiveContractSource | 업무 목표 계약을 코드로 선언할 때 | 설정의 계약만 |