Pause um agente para aprovação com KV Store

Você executa um loop de agente com tool calling em uma function, armazena uma tarefa no KV Store quando o modelo pede uma ação que uma pessoa precisa aprovar, retoma a tarefa com a decisão e grava cada evento da tarefa no SQL Database, com a Azion CLI e o código de uma function.

Pré-requisitos

Uma aplicação e um workload que servem o seu domínio, com o Application Accelerator ativado, que o behavior Run Function exige. Para criá-los, consulte Primeiros passos com Applications.
KV Store e SQL Database habilitados na conta. Os dois estão em Preview e não vêm habilitados por padrão, então solicite acesso pelo Technical Support.
O namespace agent-state do KV Store. Para criá-lo, consulte Crie o namespace.
O banco de dados agent-history, com uma tabela criada pela instrução CREATE TABLE task_events (task_id TEXT NOT NULL, event TEXT NOT NULL, steps INTEGER NOT NULL, at TEXT NOT NULL);. Para criar o banco de dados e enviar a instrução, consulte Crie um banco de dados usando a API e Crie uma tabela pela API.
Um personal token com a permissão Edit SQL Database, para as gravações do histórico. Para criar um, consulte Gerencie personal tokens.
A Azion CLI, instalada e autorizada, para armazenar as variáveis de ambiente.
Um provedor de terceiros cujo endpoint de chat aceite o formato de chat completions da OpenAI com definições de ferramentas, com a URL dele, o nome de um modelo que suporte tool calling e uma API key.

Os exemplos dão ao agente duas ferramentas sobre um serviço de pedidos em https://api.example.com/v1: get_order, que lê GET /orders/{id}, e refund_order, que chama POST /orders/{id}/refunds e precisa da aprovação de uma pessoa. Eles usam www.example.com para o domínio. Substitua-os pelos seus valores.

Armazene os valores que a function lê

A chave do provedor, o token do backend, o segredo de quem aprova e o personal token ficam fora do código, como variáveis de ambiente.

Para armazenar os valores que a function lê, execute estes comandos com a Azion CLI. Uma key que contém key, token ou secret é armazenada como secret por padrão:

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

A conta guarda as sete variáveis que a function do agente lê com Azion.env.get().

O caso de uso Criar agentes de IA usa os valores deste exemplo.

Crie a function do agente

A function executa o loop em /api/agent/tasks e o retoma em /api/agent/approve. Uma ferramenta em APPROVAL_TOOLS nunca é executada a partir do loop: a function armazena a tarefa sob task:<task-id> em agent-state por um dia e executa a ferramenta apenas quando uma pessoa a aprova.

Crie uma function chamada ops-agent com este código. A chamada ao provedor envia a chave como Authorization: Bearer; mude esse header para o que o seu provedor exige:

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};

Para criar a function e a sua instância, siga Primeiros passos com Functions com o nome ops-agent e dê à instância o nome ops-agent, sem Args.

A aplicação tem uma instância ops-agent que executa uma tarefa até que o modelo responda, um reembolso precise de aprovação ou seis etapas passem.

O caso de uso Criar agentes de IA usa os valores deste exemplo.

Execute a function nos caminhos do agente

Uma regra executa a instância nos dois caminhos do agente. Os dois recebem POST, e a function responde a qualquer outro método com 405.

Crie uma regra de Request Phase como Crie a regra para o caminho e o método descreve, com estes valores: o nome agent - tasks and approvals, um grupo de critérios com ${uri} starts with /api/agent/ no lugar dos grupos de caminho e de método do guia, e o behavior Run Function selecionando a instância ops-agent.

Uma tarefa enviada para /api/agent/tasks executa o agente, e cada início, pausa, decisão e fim chega a task_events. Uma regra nova leva alguns minutos para se propagar.

Confirme que uma tarefa pausa e retoma uma vez

Para enviar uma tarefa que precisa apenas de 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>?"}'

A resposta traz "status":"completed", uma answer que informa o status do pedido e steps igual a 2 ou mais: uma etapa que chama get_order e uma que responde.

Envie {"task":"Refund order <order-id>, the customer received a damaged item."} para o mesmo caminho. A resposta traz "status":"awaiting_approval", o task_id e uma action que indica refund_order com o ID do pedido, e o serviço de pedidos não recebeu nenhum reembolso.

Para aprovar o reembolso, envie o task_id dessa resposta com o segredo de quem aprova:

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}'

A resposta traz "status":"completed", e o serviço de pedidos recebeu um reembolso. A mesma requisição enviada de novo responde 404 com no pending action for this task, e uma requisição sem o header Authorization responde 401.

Para ler os eventos da tarefa de reembolso, envie a instrução SELECT event, steps FROM task_events WHERE task_id = '<task-id>' ORDER BY rowid; à API do SQL Database, como mostra Consulte linhas. As linhas de results listam started, awaiting_approval, approved e completed, nessa ordem.

O agente pausa antes do reembolso, o executa uma vez depois da aprovação e registra cada evento em task_events.

Estas verificações confirmam o caso de uso Criar agentes de IA.

Próximos passos

Grave linhas no SQL Database a partir de uma functionArmazene as credenciais do banco de dados e verifique o resultado de cada instrução que uma function envia.Criar agentes de IAO design a que esta function serve: o limite de etapas, a regra de aprovação e os armazenamentos, com o motivo de cada um.