kf agent
Install, suspend, resume, and scope tenant-bound agents.
kf agent grant-scope
Grant additional scope strings to an active agent installation, unioning the new scopes into capability_grant.scopes and emitting agent.scope.granted.
Grant additional scope strings to an active agent installation, unioning the new scopes into capability_grant.scopes and emitting agent.scope.granted. Idempotent on (tenantId, environmentId, command_type, idempotencyKey); requested scopes that are already a subset of the existing grant return reason 'no_op' and do not re-emit. PAUSED, REVOKED, EXPIRED, or PENDING installations soft-fail with reason 'installation_not_active'. Unresolvable targets soft-fail with reason 'installation_not_found'. Risk class R3 per the H2 hardening plan because adding scope widens the agent's authority surface; the H5 approval-binding work layers (commandType, resourceId=installationId, scope, ttl) binding on top.
| Flag | Required | Description |
|---|---|---|
--tenant <id> | yes | Target tenant id. |
--environment <id> | no | Target environment id; defaults to the active profile environment. |
--actor-type <type> | yes | Actor type (USER, SYSTEM, CONNECTOR, AGENT, SERVICE). |
--actor-id <id> | yes | Actor id. |
--idempotency-key <key> | no | Idempotency key for safe retries. Generated when omitted. |
--target <value> | yes | Target. |
--scopes <value> | yes | Scopes. |
--reason <value> | no | Reason. |
Example
kf agent grant-scope --tenant tnt_demo --actor-type USER --actor-id usr_sam --target <value> --scopes <value>kf agent install
Install an agent definition into a tenant environment.
Install an agent definition into a tenant environment. Idempotent on (tenantId, environmentId, agentDefinitionId); an ACTIVE row is returned unchanged on re-install. Soft-fails with reason 'agent_definition_not_found' when the referenced definition row is missing so onboarding in a fresh DB does not break. Risk class R3 because the installation grants agent authority.
| Flag | Required | Description |
|---|---|---|
--tenant <id> | yes | Target tenant id. |
--environment <id> | no | Target environment id; defaults to the active profile environment. |
--actor-type <type> | yes | Actor type (USER, SYSTEM, CONNECTOR, AGENT, SERVICE). |
--actor-id <id> | yes | Actor id. |
--idempotency-key <key> | no | Idempotency key for safe retries. Generated when omitted. |
--agent-definition-id <value> | yes | Agent definition id. |
--mode <value> | no | Mode. |
--capability-grant <value> | no | Capability grant. |
Example
kf agent install --tenant tnt_demo --actor-type USER --actor-id usr_sam --agent-definition-id <value>kf agent resume
Resume a paused agent installation, flipping its status from PAUSED to ACTIVE and emitting agent.resume.applied.
Resume a paused agent installation, flipping its status from PAUSED to ACTIVE and emitting agent.resume.applied. Companion to SuspendAgent. Idempotent on (tenantId, environmentId, command_type, idempotencyKey); an already-ACTIVE row replays without re-emitting; PENDING rows soft-fail with reason 'not_paused'; REVOKED/EXPIRED rows soft-fail with reason 'terminal_status'. Risk class R2 per the H2 hardening plan because Resume restores authority paused by an operator. The 'fresh approval if last suspend was a security review' gate ships with the H5 approval-binding work.
| Flag | Required | Description |
|---|---|---|
--tenant <id> | yes | Target tenant id. |
--environment <id> | no | Target environment id; defaults to the active profile environment. |
--actor-type <type> | yes | Actor type (USER, SYSTEM, CONNECTOR, AGENT, SERVICE). |
--actor-id <id> | yes | Actor id. |
--idempotency-key <key> | no | Idempotency key for safe retries. Generated when omitted. |
--target <value> | yes | Target. |
--reason <value> | no | Reason. |
Example
kf agent resume --tenant tnt_demo --actor-type USER --actor-id usr_sam --target <value>kf agent revoke-scope
Revoke scope strings from an agent installation, subtracting them from capability_grant.scopes and emitting agent.scope.revoked.
Revoke scope strings from an agent installation, subtracting them from capability_grant.scopes and emitting agent.scope.revoked. Companion to GrantAgentScope. Idempotent on (tenantId, environmentId, command_type, idempotencyKey); requested scopes that are not in the existing grant are silently ignored (no_op replay). Runs against ACTIVE and PAUSED installations because revoking scope on a paused installation is part of the security-review path. Unresolvable targets soft-fail with reason 'installation_not_found'. Risk class R2 per the H2 hardening plan because subtracting scope cannot expand authority.
| Flag | Required | Description |
|---|---|---|
--tenant <id> | yes | Target tenant id. |
--environment <id> | no | Target environment id; defaults to the active profile environment. |
--actor-type <type> | yes | Actor type (USER, SYSTEM, CONNECTOR, AGENT, SERVICE). |
--actor-id <id> | yes | Actor id. |
--idempotency-key <key> | no | Idempotency key for safe retries. Generated when omitted. |
--target <value> | yes | Target. |
--scopes <value> | yes | Scopes. |
--reason <value> | no | Reason. |
Example
kf agent revoke-scope --tenant tnt_demo --actor-type USER --actor-id usr_sam --target <value> --scopes <value>kf agent suspend
Suspend an active agent installation, flipping its status to PAUSED and emitting agent.suspend.applied.
Suspend an active agent installation, flipping its status to PAUSED and emitting agent.suspend.applied. Idempotent on (tenantId, environmentId, command_type, idempotencyKey); an already-PAUSED row replays without re-emitting. REVOKED/EXPIRED rows soft-fail with reason 'terminal_status'; unresolvable targets soft-fail with reason 'installation_not_found' so a stale operator UI cannot break the receipt chain. Risk class R1 per the H2 hardening plan; policy enforcement on PAUSED installations is the runtime gate.
| Flag | Required | Description |
|---|---|---|
--tenant <id> | yes | Target tenant id. |
--environment <id> | no | Target environment id; defaults to the active profile environment. |
--actor-type <type> | yes | Actor type (USER, SYSTEM, CONNECTOR, AGENT, SERVICE). |
--actor-id <id> | yes | Actor id. |
--idempotency-key <key> | no | Idempotency key for safe retries. Generated when omitted. |
--target <value> | yes | Target. |
--reason <value> | yes | Reason. |
Example
kf agent suspend --tenant tnt_demo --actor-type USER --actor-id usr_sam --target <value> --reason <value>