Skip to content
Kavachकवच

Standard Library: std.agents

● Intermediate5 min

Every type, method and function of std.agents: what the spec lists, then each declaration in its source, with its examples and the line that declares it.

Spec 14.16 · learn it in Agents.

A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.

spec 14.16 · std.agentsthe examples, tested

What the spec lists

FunctionGives
agents.call_key() -> String?Inside a capability's implementation, called from a durable agent's handler (8.5): the key of the running call, the same in the run after a crash, such as RefundBot-7-2 (the agent, the event's number, the call's place in it). none anywhere else
agents.waiting() -> [ApprovalRequest]The approval requests (8.3) that wait for an answer in the project's agents folder (8.5), oldest first. Needs Approvals
agents.answer(id, approved: Bool, by: String, reason: String? = none) ! ApprovalErrorAnswers request id, as kavach approve and kavach deny do (10.5). by names the person who answers; it goes to the audit log. Needs Approvals

An ApprovalRequest has these fields, all String:

FieldHolds
idThe request's number, RefundBot-17-2 (8.3)
agent_nameThe agent that asks, RefundBot
callThe call waiting, with secrets hidden: Payments.refund(order_id: 17, amount: 6000, card: <secret>)
byThe role asked, finance
whyThe rule that asked: amount > 5_000
asked, untilWhen it was asked and when it runs out, in UTC: 2026-11-06T09:30:00Z

std.agents · agents.kav

use std.agents: 2 types and 2 functions. stdlib/agents/agents.kav

ApprovalRequest type

A request that waits for a person's answer (spec 8.3).

pub type ApprovalRequest {
    /// The request's number, `RefundBot-17-2`.
    pub id: String
    /// The agent that asks, `RefundBot`.
    pub agent_name: String
    /// The call waiting, with secrets hidden.
    pub call: String
    /// The role asked, `finance`.
    pub by: String
    /// The rule that asked, `amount > 5_000`.
    pub why: String
    /// When it was asked and when it runs out, in UTC.
    pub asked: String
    pub until: String
}

ApprovalError type

Why an answer wasn't given.

pub type ApprovalError = NotWaiting(id: String) | Failed(id: String, reason: String)

waiting function

The requests that wait for an answer, oldest first.

pub fn waiting() -> [ApprovalRequest] uses Approvals

answer function

Answers request id, as kavach approve and kavach deny do. by names the person who answers; it goes to the audit log.

pub fn answer(id: String, approved: Bool, by: String, reason: String? = none) ! ApprovalError uses Approvals