diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index 54eeb83..64f6176 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -239,7 +239,9 @@ export type AsyncToolDefinition = O "execute" > & { execute(input: z.output, context: AsyncToolContext): Promise; - /** Defaults to three attempts. Use `callId` as an idempotency key for external writes. */ + /** Defaults to three attempts, so an external write can repeat. Use + * `${invocationId}:${name}:${callId}` as its idempotency key: the model supplies + * `callId`, which is not unique across runs or invocations. */ retry?: RetryOptions; }; export type RunResult = {steps: number; messages: Message[]; usage: RunUsage} & ( diff --git a/packages/examples/README.md b/packages/examples/README.md index baf58f7..82814c4 100644 --- a/packages/examples/README.md +++ b/packages/examples/README.md @@ -578,8 +578,11 @@ function* performWithRetry() { Without an explicit policy, `asyncTool` and the model adapters use three attempts. A supplied policy replaces that default; specify `maxAttempts` when you want a fixed attempt limit. The retry duration limits retries, not the -execution time of one attempt. Pass `callId` as an idempotency key for external -writes, since a retried attempt can repeat an effect. +execution time of one attempt. A retried attempt can repeat an external write, so +give each write an idempotency key built from the tool context's `invocationId`, +`name`, and `callId`, such as `` `${invocationId}:${name}:${callId}` ``. Do not use +`callId` alone: the model supplies it, and it is not unique across runs or +invocations. A throttled model call waits as long as the provider asks before its next attempt: `aiModel` reads the `retry-after-ms` and `retry-after` response diff --git a/packages/examples/src/lessons/05_evaluator_optimizer.ts b/packages/examples/src/lessons/05_evaluator_optimizer.ts index 7f0f405..6e82c3d 100644 --- a/packages/examples/src/lessons/05_evaluator_optimizer.ts +++ b/packages/examples/src/lessons/05_evaluator_optimizer.ts @@ -56,7 +56,7 @@ export const codeReview = restate.service({ let code = ""; let feedback = ""; for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) { - // Distinct run names keep event IDs and approval namespaces independent. + // Distinct run names keep approval signals and idempotency keys apart. const draft = yield* generator.run(JSON.stringify({task, previousCode: code, feedback}), { name: `write-${iteration}`, }); diff --git a/plugins/restate-agents/skills/restate-agents/SKILL.md b/plugins/restate-agents/skills/restate-agents/SKILL.md index 56256e3..a1be3ae 100644 --- a/plugins/restate-agents/skills/restate-agents/SKILL.md +++ b/plugins/restate-agents/skills/restate-agents/SKILL.md @@ -121,12 +121,14 @@ Restate journals. Move on only when the learner is ready. `maxSteps` or `maxToolCalls`), and `interrupted`. Do not read `output` as the answer unless the status is `completed`. - [ ] Give each run a distinct `name` when one handler runs the same agent - more than once (loops, races), so journal entries and approval signals - stay apart. + more than once (loops, races). The name scopes the run's approval + signals and idempotency keys. It does not separate journal entries, + which Restate matches by position. - [ ] Tool side effects run in `asyncTool.execute` or `restate.run`. Code in a `tool` generator outside those is replayed. -- [ ] Give external writes an idempotency key (`context.callId` is stable - across retries). +- [ ] Give external writes an idempotency key built from the tool context's + `invocationId`, `name`, and `callId`. Do not use `callId` alone: the + model supplies it, and it is not unique across runs or invocations. - [ ] Throw `TerminalError` for failures the model should handle, or `ToolError` to also give the model an error code. From a tool or a hook, the model receives the error and the run continues. Throw diff --git a/plugins/restate-agents/skills/restate-agents/references/error-handling.md b/plugins/restate-agents/skills/restate-agents/references/error-handling.md index c267ec4..18296b2 100644 --- a/plugins/restate-agents/skills/restate-agents/references/error-handling.md +++ b/plugins/restate-agents/skills/restate-agents/references/error-handling.md @@ -47,13 +47,14 @@ import {AgentTerminalError, asyncTool, ToolError} from "@restatedev/agentlib"; refund: asyncTool({ description: "Refund an order.", input: z.object({orderId: z.string()}), - async execute({orderId}, {context, callId}) { + async execute({orderId}, {context, invocationId, name, callId}) { const order = await orders.get(orderId); // a network error: retried if (!order) throw new ToolError(`No order ${orderId}`, "not_found"); // the model gets the code if (order.refunded) throw new TerminalError("The order was already refunded"); // the model decides if (order.customerId !== context.customerId) throw new AgentTerminalError("The order belongs to another customer"); // the run fails - return await payments.refund(orderId, {idempotencyKey: callId}); + const idempotencyKey = `${invocationId}:${name}:${callId}`; // the same on every retry + return await payments.refund(orderId, {idempotencyKey}); }, }), ``` diff --git a/plugins/restate-agents/skills/restate-agents/references/multi-agent.md b/plugins/restate-agents/skills/restate-agents/references/multi-agent.md index ef3d662..d8ee1ea 100644 --- a/plugins/restate-agents/skills/restate-agents/references/multi-agent.md +++ b/plugins/restate-agents/skills/restate-agents/references/multi-agent.md @@ -43,7 +43,7 @@ function* (question) { ## Draft and review, bounded Loop over two structured agents. Give each run a distinct `name` so their -journal entries and approval signals stay apart. +approval signals and idempotency keys stay apart. ```ts for (let i = 1; i <= 3; i++) {