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
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ starting the work over.
- **Compose agents like services.** Call other handlers through durable RPC,
delegate to sub-agents, or hand a conversation to a specialist.
- **Bring the tools you need.** Use async functions, Restate services, MCP,
tool search, background work, and programmatic tool calling.
tool search, background work, and code mode (programmatic tool calling).

[Start from the template](https://github.com/restatedev/agentlib-template) ·
[Run the tutorial](#try-it) · [Explore the capabilities](#capabilities) ·
Expand Down Expand Up @@ -152,8 +152,8 @@ repeat a completed model call.
| Sub-agents as tools | `agentTool` | — |
| Restate services as tools | `serviceTool`, `handlerTool`, `restateTools` (`/discovery`) | [10](packages/examples/src/lessons/10_service_tool.ts) |
| Background tools | `background: true`, `sleepTool`, `cancelOperationTool` | — |
| Tool search | `searchToolsTool`, `deferred: true` | — |
| Programmatic tool calling | `programTool` (`/program`), run in a QuickJS sandbox | — |
| Tool search | `deferred: true`; `agent({toolSearch})`, on by default | — |
| Code mode | `agent({codeMode})`, on by default, in QuickJS; `programTool` (`/program`) | — |
| MCP | `mcpTools` (`/mcp`), passed as `run(input, {tools})` | [17](packages/examples/src/lessons/17_mcp_tools.ts) |
| AG-UI clients | `onProgress`, `onApproval` and client-run tools as AG-UI events | [18](packages/examples/src/lessons/18_ag_ui.ts) |
| Guardrails | `beforeRun`, `beforeStep`, `beforeTool`, `afterTool`, `afterRun`, `before` | [13](packages/examples/src/lessons/13_tool_guardrail.ts) |
Expand Down
2 changes: 1 addition & 1 deletion packages/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ go from a first run to multi-agent workflows.
| `@restatedev/agentlib` | Agents, tools, conversations, guardrails |
| `@restatedev/agentlib/provider` | Models through the Vercel AI SDK providers |
| `@restatedev/agentlib/mcp` | Tools from MCP servers |
| `@restatedev/agentlib/program` | Programmatic tool calling in a sandbox |
| `@restatedev/agentlib/program` | Code mode with custom tools and limits |
| `@restatedev/agentlib/discovery` | Expose agents and tools for discovery |

## License
Expand Down
39 changes: 35 additions & 4 deletions packages/core/src/agent-run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ import {summarizeContext, truncateContext} from "./context-compaction.js";
import {estimateTokens, jsonTokens, textTokens} from "./context-size.js";
import {READ_TOOL, readToolResultTool, type PreviewSettings} from "./tool-result-preview.js";
import {listSkills, skillsSection, skillTools} from "./skills.js";
import {SEARCH_TOOL, searchToolsTool} from "./builtins.js";
import {PROGRAM_TOOL, programTool} from "./program.js";
import {jsonSchema, modelResponse, stepMessages, steeringUpdate} from "./validation.js";
import type {
AgentOptions,
Expand Down Expand Up @@ -62,6 +64,10 @@ export type RunConfiguration = ToolExecutionLimits &
contextWindow?: number;
}>;

// The tools a run adds by default hold no state, so every run shares them.
const defaultSearch = searchToolsTool();
const defaultProgram = programTool();

export function* runAgent<C, O>(
input: string,
root: AgentOptions<C, O>,
Expand Down Expand Up @@ -356,12 +362,16 @@ class AgentRun<C, O> {
return readerOnly && !this.history.hasPreviews() ? [] : tools;
}

/** Tools that belong to the run rather than an agent, so they survive a handoff. */
/** Tools that belong to the run rather than an agent, so they survive a handoff.
* Search and code mode depend on the active agent's tools, so the run
* decides on them again after a handoff. */
private runTools(): Record<string, Tool<C>> {
const tools = {...this.options?.tools};
for (const [name, skillTool] of Object.entries(this.skills?.tools ?? {})) {
const own = [...Object.values(this.active.tools ?? {}), ...Object.values(tools)];
const added = {...this.skills?.tools, ...this.defaultTools(own)};
for (const [name, runTool] of Object.entries(added)) {
if (name in tools) throw new TypeError(`Duplicate tool name: ${name}`);
tools[name] = skillTool;
tools[name] = runTool;
}
const settings = this.config.toolResults;
if (!settings) return tools;
Expand All @@ -370,6 +380,26 @@ class AgentRun<C, O> {
return tools;
}

/** Search when a tool is deferred, and code mode when a program has a tool
* to call. An agent turns either off, or brings its own tool in its tools. */
private defaultTools(own: Tool<C>[]): Record<string, Tool<C>> {
const tools: Record<string, Tool<C>> = {};
if (
this.root.toolSearch !== false &&
!own.some((definition) => definition.search) &&
own.some((definition) => definition.deferred)
)
tools[SEARCH_TOOL] = defaultSearch;
// A program cannot hand off, and has no use for search on its own.
if (
this.root.codeMode !== false &&
!own.some((definition) => definition.program) &&
own.some((definition) => !definition.handoff && !definition.search)
)
tools[PROGRAM_TOOL] = defaultProgram;
return tools;
}

private *emit(event: ProgressEvent): Operation<void> {
// Called as a method, so a handler can use `this`, like onApproval.
if (this.options?.onProgress)
Expand Down Expand Up @@ -447,7 +477,8 @@ class AgentRun<C, O> {
if (transfer) {
this.active = transfer();
yield* this.emit({type: "handoff", agent: this.active.name});
// Run-level tools belong to the run, not the agent, so they survive a handoff.
// Run-level tools belong to the run, not the agent, so they survive a handoff;
// search and code mode follow the new agent's tools.
this.catalog = createToolCatalog(this.active.tools, this.runTools());
}
}
Expand Down
3 changes: 3 additions & 0 deletions packages/core/src/builtins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ export function cancelOperationTool(
});
}

/** The name of the search tool a run adds when an agent has deferred tools. */
export const SEARCH_TOOL = "search_tools";

export function searchToolsTool(options: BuiltinToolOptions<{query: string}> = {}) {
return {
...tool({
Expand Down
File renamed without changes.
9 changes: 6 additions & 3 deletions packages/core/src/program.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {z} from "zod";
import {ToolError} from "./errors.js";
import {guestLimits, ProgramError, type GuestLimits, type Json} from "./ptc/guest.js";
import {executeProgram} from "./ptc/runtime.js";
import {guestLimits, ProgramError, type GuestLimits, type Json} from "./code-mode/guest.js";
import {executeProgram} from "./code-mode/runtime.js";
import type {BuiltinToolOptions} from "./builtins.js";
import {tool} from "./tool.js";

Expand Down Expand Up @@ -29,6 +29,9 @@ function callSummary(calls: {name: string; status: CallStatus}[]): string {
return `Tool calls made before the failure, which are not undone: ${tools.join(", ")}.`;
}

/** The name of the tool a run adds for code mode when an agent has tools to call. */
export const PROGRAM_TOOL = "run_program";

/** QuickJS orchestrates the same permitted, policy-checked tools as direct calls. */
export function programTool(
options: {tools?: string[]; limits?: GuestLimits} & BuiltinToolOptions<{source: string}> = {},
Expand Down Expand Up @@ -97,4 +100,4 @@ export function programTool(
});
return {...program, program: true as const};
}
export type {GuestLimits} from "./ptc/guest.js";
export type {GuestLimits} from "./code-mode/guest.js";
13 changes: 13 additions & 0 deletions packages/core/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,19 @@ export type AgentOptions<Context, Output = string> = {
* loaded history. The saved and returned transcript keeps every result whole.
* `false` shows every result in full. */
toolResults?: false | {maxTokens?: number; previewTokens?: number};
/** Adds `search_tools` when the agent or the run has a `deferred` tool. The
* model then sees a deferred tool's schema only after a search loads it,
* which keeps a large catalog out of every request. A search tool in
* `tools`, such as `searchToolsTool()`, replaces it. `false` leaves it out,
* and deferred tools are listed like any other. Default: true. */
toolSearch?: boolean;
/** Code mode (programmatic tool calling): adds `run_program` when the agent
* or the run has a tool a program can call. The model writes one JavaScript
* program, run in a QuickJS sandbox, that calls several tools and returns
* only the compact result. A program tool in `tools`, such as
* `programTool({limits})` from `/program`, replaces it. `false` leaves it
* out. Default: true. */
codeMode?: boolean;
/** Skills the model can load when a task needs them. The run lists them once
* at its start, after the instructions, and adds `load_skill` (and
* `read_skill_file` when the source can read files). They belong to the
Expand Down
144 changes: 136 additions & 8 deletions packages/tests/src/catalog-program.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,21 @@ import MiniSearch from "minisearch";
import {z} from "zod";
import {
agent,
type AgentOptions,
cancelOperationTool,
handoff,
type ModelResponse,
type RunOptions,
searchToolsTool,
tool,
type ModelResponse,
ToolError,
type ToolResult,
} from "@restatedev/agentlib";
import {programTool} from "@restatedev/agentlib/program";
import {runHandler} from "./replay-harness.mjs";
import {testContext} from "./helpers.js";
const done: ModelResponse = {type: "final", text: "done"};
const context = () => testContext("ptc");
const context = () => testContext("code-mode");

void test("tool search loads permitted schemas, resets between runs, and journals ranking", async (t) => {
const a = agent({
Expand All @@ -37,7 +40,7 @@ void test("tool search loads permitted schemas, resets between runs, and journal
if (!req.messages.some((m) => m.role === "tool")) {
assert.deepEqual(
req.tools.map((t) => t.name),
["find", "read_tool_result"],
["find", "run_program", "read_tool_result"],
);
return {
type: "tool_calls",
Expand All @@ -46,7 +49,7 @@ void test("tool search loads permitted schemas, resets between runs, and journal
}
assert.deepEqual(
req.tools.map((t) => t.name),
["find", "github_notifications", "read_tool_result"],
["find", "github_notifications", "run_program", "read_tool_result"],
);
return done;
},
Expand All @@ -62,10 +65,11 @@ void test("tool search loads permitted schemas, resets between runs, and journal
assert.deepEqual(replay.output, first.output);
});

void test("deferred tools stay visible when search is not installed", async () => {
void test("deferred tools stay visible when toolSearch is false", async () => {
await r.execute(
context(),
agent({
toolSearch: false,
tools: {
lookup: tool({
description: "find",
Expand All @@ -84,7 +88,131 @@ void test("deferred tools stay visible when search is not installed", async () =
);
});

void test("PTC shares approval and output policies while keeping intermediate results out of model context", async () => {
void test("a run searches deferred tools and turns on code mode by default", async () => {
let step = 0;
const a = agent({
tools: {
weather: tool({
description: "Current weather in a city",
deferred: true,
input: z.object({city: z.string()}),
*execute({city}) {
return `${city}: sunny`;
},
}),
cities: tool({
description: "List the cities to report on",
input: z.object({}),
*execute() {
return ["Ghent", "Berlin"];
},
}),
},
*model(req) {
const names = req.tools.map((t) => t.name);
if (++step === 1) {
// The deferred tool stays hidden until a search loads it.
assert.deepEqual(names, ["cities", "search_tools", "run_program", "read_tool_result"]);
return {
type: "tool_calls",
calls: [{id: "s", name: "search_tools", input: {query: "weather"}}],
};
}
if (step === 2) {
assert.deepEqual(names, [
"weather",
"cities",
"search_tools",
"run_program",
"read_tool_result",
]);
const source =
"const cities = await tools.cities({}); return await Promise.all(cities.map((city) => tools.weather({city})));";
return {type: "tool_calls", calls: [{id: "p", name: "run_program", input: {source}}]};
}
const program = req.messages.find((m) => m.role === "tool" && m.callId === "p");
assert.deepEqual(program?.role === "tool" && program.result, {
status: "success",
output: ["Ghent: sunny", "Berlin: sunny"],
});
return done;
},
});
// Search journals its ranking, so this run needs a journal.
const handler = (ctx: Context) => r.execute(ctx, a.run("go"));
const first = await runHandler(handler);
assert.equal(first.output.status, "completed");
step = 0;
const replay = await runHandler(handler, {replay: first.journal});
assert.deepEqual(replay.output, first.output);
});

void test("an agent turns the default tools off or replaces them with its own", async () => {
const lookup = tool({
description: "find",
deferred: true,
input: z.object({}),
*execute() {
return 1;
},
});
const listed = async (
options: Omit<AgentOptions<undefined>, "model">,
tools?: RunOptions<undefined>["tools"],
) => {
let names: string[] = [];
const a = agent({
...options,
*model(req) {
names = req.tools.map((t) => t.name);
return done;
},
});
await r.execute(context(), a.run("go", {tools}));
return names;
};
assert.deepEqual(await listed({tools: {lookup}, toolSearch: false, codeMode: false}), [
"lookup",
"read_tool_result",
]);
assert.deepEqual(
await listed({tools: {find: searchToolsTool(), program: programTool(), lookup}}),
["find", "program", "read_tool_result"],
);
// Deferred tools passed to the run, such as MCP tools, are searched too.
assert.deepEqual(await listed({}, {lookup}), ["search_tools", "run_program", "read_tool_result"]);
// Without tools, or with only a handoff, a program has nothing to call.
assert.deepEqual(await listed({}), []);
const specialist = agent({
*model() {
return done;
},
});
assert.deepEqual(await listed({tools: {transfer: handoff(specialist)}}), [
"transfer",
"read_tool_result",
]);
});

void test("a tool that takes a default tool's name fails the run", async () => {
const a = agent({
tools: {
run_program: tool({
description: "Run a TV program",
input: z.object({}),
*execute() {
return null;
},
}),
},
*model() {
return done;
},
});
await assert.rejects(r.execute(context(), a.run("go")), /Duplicate tool name: run_program/);
});

void test("Code mode shares approval and output policies while keeping intermediate results out of model context", async () => {
let calls = 0,
step = 0,
approvals = 0;
Expand Down Expand Up @@ -212,7 +340,7 @@ void test("a program that fails before calling a tool says so", async () => {
assert.match(message ?? "", /SyntaxError[^]*\n\nNo tool calls were made\.$/);
});

void test("PTC failure and child cleanup remain native through the full agent dispatcher", async () => {
void test("Code mode failure and child cleanup remain native through the full agent dispatcher", async () => {
let cleaned = false,
step = 0;
const a = agent({
Expand Down Expand Up @@ -258,7 +386,7 @@ void test("PTC failure and child cleanup remain native through the full agent di
assert.equal(cleaned, true);
});

void test("PTC runs and nested durable effects replay without invoking the host again", async () => {
void test("Code mode runs and nested durable effects replay without invoking the host again", async () => {
let effects = 0;
const a = agent({
tools: {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {type Context, TerminalError} from "@restatedev/restate-sdk";
import {execute, gen, run} from "@restatedev/restate-sdk-gen";
import type {GuestLimits, Json, Outcome} from "../../core/src/ptc/guest.js";
import {executeProgram} from "../../core/src/ptc/runtime.js";
import type {GuestLimits, Json, Outcome} from "../../core/src/code-mode/guest.js";
import {executeProgram} from "../../core/src/code-mode/runtime.js";

// Runs the production driver inside the real SDK scheduler. Each supplied test
// tool owns a run, just as concrete agent tools own their durable operations.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ import {
unknownTool,
type Outcome,
type Request,
} from "../../core/src/ptc/guest.js";
import {executeWithTools as executeProgram} from "./ptc-adapter.js";
} from "../../core/src/code-mode/guest.js";
import {executeWithTools as executeProgram} from "./code-mode-adapter.js";

void test("invalid guest budgets fail before allocating a VM", () => {
for (const key of ["maxInterruptChecks", "maxJobsPerDrain", "maxToolCalls"] as const) {
Expand Down
Loading
Loading