Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion packages/core/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,9 @@ export type AsyncToolDefinition<Schema extends z.ZodType, Context = unknown> = O
"execute"
> & {
execute(input: z.output<Schema>, context: AsyncToolContext<Context>): Promise<JsonValue>;
/** 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<Output = string> = {steps: number; messages: Message[]; usage: RunUsage} & (
Expand Down
7 changes: 5 additions & 2 deletions packages/examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/examples/src/lessons/05_evaluator_optimizer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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}`,
});
Expand Down
10 changes: 6 additions & 4 deletions plugins/restate-agents/skills/restate-agents/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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});
},
}),
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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++) {
Expand Down
Loading