Pause an agent for approval with KV Store

You run a tool-calling agent loop in a function, store a task in KV Store when the model asks for an action a person must approve, resume it on the decision, and write every task event to SQL Database, with the Azion CLI and a function’s code.

Prerequisites

An application and a workload that serve your domain, with Application Accelerator turned on, which the Run Function behavior requires. To create them, refer to Applications quickstart.
KV Store and SQL Database enabled on the account. Both are in Preview and not enabled by default, so request access through Technical Support.
The agent-state KV Store namespace. To create it, refer to Create the namespace.
The agent-history database, with a table created by the statement CREATE TABLE task_events (task_id TEXT NOT NULL, event TEXT NOT NULL, steps INTEGER NOT NULL, at TEXT NOT NULL);. To create the database and send the statement, refer to Create a database using the API and Create a table using the API.
A personal token with the Edit SQL Database permission, for the history writes. To create one, refer to Personal tokens.
The Azion CLI, installed and authorized, to store the environment variables.
A third-party provider whose chat endpoint accepts the OpenAI chat completions format with tool definitions, with its URL, the name of a model that supports tool calling, and an API key.

The examples give the agent two tools over an order service at https://api.example.com/v1: get_order, which reads GET /orders/{id}, and refund_order, which calls POST /orders/{id}/refunds and needs a person’s approval. They use www.example.com for the domain. Replace them with your values.

Store the values the function reads

The provider key, the backend token, the approver secret, and the personal token stay out of the code, as environment variables.

To store the values the function reads, run these commands with the Azion CLI. A key that contains key, token, or secret is stored as a secret by default:

Shell

01azion create variables --key "PROVIDER_URL" --value "<provider-chat-completions-url>" --secret false

02azion create variables --key "PROVIDER_MODEL" --value "<provider-model-name>" --secret false

03azion create variables --key "PROVIDER_API_KEY" --value "<provider-api-key>"

04azion create variables --key "BACKEND_API_TOKEN" --value "<backend-token>"

05azion create variables --key "APPROVER_SECRET" --value "<approver-secret>"

06azion create variables --key "AZION_TOKEN" --value "[TOKEN VALUE]"

07azion create variables --key "SQL_DATABASE_ID" --value "<database-id>" --secret false

The account holds the seven variables the agent function reads with Azion.env.get().

The Build AI agents use case uses the values of this example.

Create the agent function

The function runs the loop on /api/agent/tasks and resumes it on /api/agent/approve. A tool in APPROVAL_TOOLS never runs from the loop: the function stores the task under task:<task-id> in agent-state for one day, and runs the tool only when a person approves it.

Create a function named ops-agent with this code. The provider call sends the key as Authorization: Bearer; change that header to the one your provider requires:

JavaScript

01const MAX_STEPS = 6;

02const API_BASE = "https://api.example.com/v1";

03const APPROVAL_TOOLS = new Set(["refund_order"]);

04const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;

05const SYSTEM_PROMPT =

06 "You are an operations agent for an order service. Use the tools to complete the task. " +

07 "Answer with a short summary once the task is done.";

09const TOOLS = [

10 { "type": "function", "function": {

11 "name": "get_order",

12 "description": "Get one order by its ID, with its status and total.",

13 "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] }

14 } },

15 { "type": "function", "function": {

16 "name": "refund_order",

17 "description": "Refund an order in full. A person approves every refund before it runs.",

    "parameters": { "type": "object", "properties": { "order_id": { "type": "string" }, "reason": { "type": "string" } }, "required": ["order_id", "reason"] }

19 } }

20];

22async function runTool(name, args) {

23 const headers = {

24 "Authorization": `Bearer ${Azion.env.get("BACKEND_API_TOKEN")}`,

25 "Content-Type": "application/json"

26 };

27 const order = encodeURIComponent(args.order_id ?? "");

28 let response;

29 if (name === "get_order") {

30 response = await fetch(`${API_BASE}/orders/${order}`, { headers });

31 } else if (name === "refund_order") {

32 response = await fetch(`${API_BASE}/orders/${order}/refunds`, {

33 method: "POST", headers, body: JSON.stringify({ reason: args.reason })

34 });

35 } else {

36 return { error: `unknown tool ${name}` };

37 }

38 return response.ok ? await response.json() : { error: `the order service answered ${response.status}` };

39}

41async function callModel(messages) {

42 const response = await fetch(Azion.env.get("PROVIDER_URL"), {

43 method: "POST",

44 headers: {

45 "Authorization": `Bearer ${Azion.env.get("PROVIDER_API_KEY")}`,

46 "Content-Type": "application/json"

47 },

48 body: JSON.stringify({ model: Azion.env.get("PROVIDER_MODEL"), messages, tools: TOOLS })

49 });

50 if (!response.ok) throw new Error(`provider answered ${response.status}`);

51 const body = await response.json();

52 return body?.choices?.[0]?.message;

53}

55async function record(taskId, event, steps) {

56 const statement =

57 `INSERT INTO task_events (task_id, event, steps, at) VALUES ('${taskId}', '${event}', ${steps}, datetime('now'));`;

58 const response = await fetch(

59 `https://api.azion.com/v4/workspace/sql/databases/${Azion.env.get("SQL_DATABASE_ID")}/query`,

60 {

61 method: "POST",

62 headers: {

63 "Accept": "application/json",

64 "Authorization": `Token ${Azion.env.get("AZION_TOKEN")}`,

65 "Content-Type": "application/json"

66 },

67 body: JSON.stringify({ statements: [statement] })

68 }

69 );

70 const body = await response.json();

71 const failed = (body.data ?? []).find((entry) => entry.error);

72 if (!response.ok || failed) {

73 console.log(JSON.stringify({ event: "history_write_failed", taskId, error: failed?.error ?? response.status }));

74 }

75}

77async function runLoop(kv, taskId, state) {

78 while (state.steps < MAX_STEPS) {

79 state.steps++;

80 const message = await callModel(state.messages);

81 const calls = message?.tool_calls ?? [];

82 if (calls.length === 0) {

83 await record(taskId, "completed", state.steps);

84 return { task_id: taskId, status: "completed", answer: message?.content ?? "", steps: state.steps };

85 }

86 state.messages.push({

87 role: "assistant",

88 content: message.content || `Calling ${calls.map((c) => c.function?.name).join(", ")}.`

89 });

90 for (const call of calls) {

91 const name = call.function?.name;

92 const raw = call.function?.arguments ?? {};

93 const args = typeof raw === "string" ? JSON.parse(raw) : raw;

94 if (APPROVAL_TOOLS.has(name)) {

95 state.pending = { name, args };

96 await kv.put(`task:${taskId}`, state, { expirationTtl: 86400 });

97 await record(taskId, "awaiting_approval", state.steps);

98 return { task_id: taskId, status: "awaiting_approval", action: state.pending };

99 }

100 const result = await runTool(name, args);

101 state.messages.push({ role: "user", content: `Result of ${name}: ${JSON.stringify(result)}` });

102 }

103 }

104 await record(taskId, "step_limit", state.steps);

105 return { task_id: taskId, status: "step_limit", steps: state.steps };

106}

107

108export default {

109 async fetch(request, env, ctx) {

110 if (request.method !== "POST") {

111 return new Response("Method not allowed", { status: 405 });

112 }

113 const url = new URL(request.url);

114 const kv = await Azion.KV.open("agent-state");

115 let taskId = null;

116 try {

117 if (url.pathname === "/api/agent/tasks") {

118 const { task } = await request.json();

119 if (typeof task !== "string" || task.trim() === "") {

120 return Response.json({ error: "task is required" }, { status: 400 });

121 }

122 taskId = crypto.randomUUID();

123 await record(taskId, "started", 0);

124 const state = {

125 steps: 0,

126 pending: null,

127 messages: [{ role: "system", content: SYSTEM_PROMPT }, { role: "user", content: task }]

128 };

129 return Response.json(await runLoop(kv, taskId, state));

130 }

131

132 if (url.pathname === "/api/agent/approve") {

133 if (request.headers.get("Authorization") !== `Bearer ${Azion.env.get("APPROVER_SECRET")}`) {

134 return new Response("Unauthorized", { status: 401 });

135 }

136 const { task_id, approved } = await request.json();

137 if (!UUID.test(task_id ?? "")) {

138 return Response.json({ error: "task_id is not a task ID" }, { status: 400 });

139 }

140 taskId = task_id;

141 const state = await kv.get(`task:${taskId}`, "json");

142 if (!state?.pending) {

143 return Response.json({ error: "no pending action for this task" }, { status: 404 });

144 }

145 const { name, args } = state.pending;

146 state.pending = null;

147 await kv.put(`task:${taskId}`, state, { expirationTtl: 86400 });

148 await record(taskId, approved === true ? "approved" : "rejected", state.steps);

149 const result = approved === true ? await runTool(name, args) : { error: "a person rejected this action" };

150 state.messages.push({ role: "user", content: `Result of ${name}: ${JSON.stringify(result)}` });

151 return Response.json(await runLoop(kv, taskId, state));

152 }

153

154 return new Response("Not found", { status: 404 });

155 } catch (error) {

156 console.log(JSON.stringify({ event: "task_failed", taskId, error: String(error?.message ?? error) }));

157 if (taskId) await record(taskId, "failed", 0);

158

      return Response.json({ task_id: taskId, status: "failed", error: "the task could not continue" }, { status: 502 });

159 }

160 },

161};

To create the function and its instance, follow Functions quickstart with the name ops-agent, and name the instance ops-agent, with no Args.

The application carries an ops-agent instance that runs a task until the model answers, a refund needs approval, or six steps pass.

The Build AI agents use case uses the values of this example.

Run the function on the agent’s paths

One rule runs the instance on both agent paths. Both take POST, and the function answers any other method with 405.

Create a Request Phase rule as Create the rule for the path and the method describes, with these values: the name agent - tasks and approvals, one criteria group with ${uri} starts with /api/agent/ in place of the guide’s path and method groups, and the Run Function behavior selecting the ops-agent instance.

A task sent to /api/agent/tasks runs the agent, and every start, pause, decision, and end lands in task_events. A new rule takes a few minutes to propagate.

Confirm a task pauses and resumes once

To send a task that needs only get_order:

Shell

01curl -s -X POST https://www.example.com/api/agent/tasks \

02 -H 'Content-Type: application/json' \

03 -d '{"task":"What is the status of order <order-id>?"}'

The response carries "status":"completed", an answer that states the order’s status, and steps of 2 or more: one step that calls get_order, and one that answers.

Send {"task":"Refund order <order-id>, the customer received a damaged item."} to the same path. The response carries "status":"awaiting_approval", the task_id, and an action naming refund_order with the order ID, and the order service has received no refund.

To approve the refund, send the task_id from that response with the approver secret:

Shell

01curl -s -X POST https://www.example.com/api/agent/approve \

02 -H 'Authorization: Bearer <approver-secret>' \

03 -H 'Content-Type: application/json' \

04 -d '{"task_id":"<task-id>","approved":true}'

The response carries "status":"completed", and the order service has received one refund. The same request sent again answers 404 with no pending action for this task, and a request without the Authorization header answers 401.

To read the events of the refund task, send the statement SELECT event, steps FROM task_events WHERE task_id = '<task-id>' ORDER BY rowid; to the SQL Database API, as Query rows shows. The results rows list started, awaiting_approval, approved, and completed, in that order.

The agent pauses before the refund, runs it once after the approval, and records each event in task_events.

These checks confirm the Build AI agents use case.

Next steps

Write rows to SQL Database from a functionStore the database credentials and check the result of every statement a function sends.Build AI agentsThe design this function serves: the step limit, the approval rule, and the stores, with the reason for each.