Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): allow disabling agent tool (#825)

Ruidab9889c7fb3
diff --git a/.changeset/calm-agents-rest.md b/.changeset/calm-agents-rest.md
new file mode 100644
index 000000000..35a78b9c6
--- /dev/null
+++ b/.changeset/calm-agents-rest.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Allow agents to remove the root-only built-in `agent` delegation tool with `disableTool()` from `agent/tools/agent.ts`.
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.md
index c680253f6..96a1d557f 100644
--- a/docs/concepts/default-harness.md
+++ b/docs/concepts/default-harness.md
@@ -79,6 +79,8 @@ import { disableTool } from "eve/tools";
export default disableTool();
```
+Use `agent/tools/agent.ts` to remove the root-only `agent` delegation tool. The root session then receives no recursive delegation capability, and the model never sees the tool.
+
If the filename matches no known framework tool, resolution fails instead of silently doing nothing, so a typo surfaces at build time rather than removing the wrong tool.
## When to override, disable, or author a new tool
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index 0c1b8b7f3..b6908fd72 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -22,6 +22,14 @@ The copy uses the root's instructions, connections, auth, and sandbox. It receiv
The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
+To prevent the root session from delegating, disable `agent` the same way as any other built-in tool:
+
+```ts title="agent/tools/agent.ts"
+import { disableTool } from "eve/tools";
+
+export default disableTool();
+```
+
An authored root tool at `agent/tools/agent.ts` takes priority over the built-in.
## Declared subagents
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index 69622b67e..e87c34105 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -191,8 +191,13 @@ function createTestNode(
turnAgent?: RuntimeTurnAgent,
overrides: Partial<ResolvedRuntimeAgentNode> = {},
): ResolvedRuntimeAgentNode {
+ const agent = {} as ResolvedRuntimeAgentNode["agent"];
+
return {
- agent: {} as ResolvedRuntimeAgentNode["agent"],
+ agent: {
+ ...agent,
+ disabledFrameworkTools: [],
+ },
channels: [],
hookRegistry: createEmptyHookRegistry(),
nodeId: ROOT_RUNTIME_AGENT_NODE_ID,
@@ -239,6 +244,21 @@ describe("createNodeHarnessTools", () => {
expect(tools.has("agent")).toBe(false);
});
+
+ it("does not give the root node a recursive agent tool when it is disabled", () => {
+ const node = createTestNode();
+ const tools = createNodeHarnessTools({
+ node: {
+ ...node,
+ agent: {
+ ...node.agent,
+ disabledFrameworkTools: ["agent"],
+ },
+ },
+ });
+
+ expect(tools.has("agent")).toBe(false);
+ });
});
describe("createExecutionNodeStep", () => {
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index 2781cc8f1..c5f8176cd 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -14,6 +14,7 @@ import {
type RuntimeModelResolutionScope,
} from "#runtime/agent/resolve-model.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";
import { ROOT_RUNTIME_AGENT_NODE_ID, type ResolvedRuntimeAgentNode } from "#runtime/graph.js";
import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";
@@ -25,13 +26,6 @@ import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
const log = createLogger("execution.node-step");
-const BUILT_IN_AGENT_TOOL_DESCRIPTION = [
- "Delegate a focused subtask to a fresh copy of yourself.",
- "Use it to isolate complex work or split a large task into independent pieces.",
- "Issue multiple `agent` calls in one response to run a small fixed set in parallel.",
- "Each child has fresh history and state but shares your tools and sandbox, so include essential context in `message` and give parallel writers non-overlapping scopes.",
-].join(" ");
-
/**
* Factory that creates a {@link Runtime} for the given compiled
* artifacts source and optional node id. Matches the signature of
@@ -181,16 +175,20 @@ export function createNodeHarnessTools(input: {
}
}
- if (input.node.nodeId === ROOT_RUNTIME_AGENT_NODE_ID && !tools.has("agent")) {
- tools.set("agent", {
- description: BUILT_IN_AGENT_TOOL_DESCRIPTION,
+ if (
+ input.node.nodeId === ROOT_RUNTIME_AGENT_NODE_ID &&
+ !input.node.agent.disabledFrameworkTools.includes(AGENT_TOOL_NAME) &&
+ !tools.has(AGENT_TOOL_NAME)
+ ) {
+ tools.set(AGENT_TOOL_NAME, {
+ description: AGENT_TOOL_DESCRIPTION,
inputSchema: jsonSchema(SUBAGENT_TOOL_INPUT_SCHEMA),
- name: "agent",
+ name: AGENT_TOOL_NAME,
runtimeAction: {
kind: "subagent-call",
nodeId: input.node.nodeId,
recursive: true,
- subagentName: "agent",
+ subagentName: AGENT_TOOL_NAME,
},
});
}
diff --git a/packages/eve/src/runtime/framework-tools/agent.ts b/packages/eve/src/runtime/framework-tools/agent.ts
new file mode 100644
index 000000000..6ea842e0d
--- /dev/null
+++ b/packages/eve/src/runtime/framework-tools/agent.ts
@@ -0,0 +1,14 @@
+/**
+ * Stable model-visible name for the root-only recursive agent tool.
+ */
+export const AGENT_TOOL_NAME = "agent";
+
+/**
+ * Model-facing instructions for the root-only recursive agent tool.
+ */
+export const AGENT_TOOL_DESCRIPTION = [
+ "Delegate a focused subtask to a fresh copy of yourself.",
+ "Use it to isolate complex work or split a large task into independent pieces.",
+ "Issue multiple `agent` calls in one response to run a small fixed set in parallel.",
+ "Each child has fresh history and state but shares your tools and sandbox, so include essential context in `message` and give parallel writers non-overlapping scopes.",
+].join(" ");
diff --git a/packages/eve/src/runtime/framework-tools/index.test.ts b/packages/eve/src/runtime/framework-tools/index.test.ts
index bdbe11da8..2f817cd16 100644
--- a/packages/eve/src/runtime/framework-tools/index.test.ts
+++ b/packages/eve/src/runtime/framework-tools/index.test.ts
@@ -18,6 +18,7 @@ describe("framework-tools/index", () => {
expect(names.has("todo")).toBe(true);
expect(names.has("load_skill")).toBe(true);
expect(names.has("ask_question")).toBe(true);
+ expect(names.has("agent")).toBe(true);
// connection_search is now a dynamic tool resolver, not a framework tool
expect(names.has("connection_search")).toBe(false);
});
diff --git a/packages/eve/src/runtime/framework-tools/index.ts b/packages/eve/src/runtime/framework-tools/index.ts
index f5f7ec953..97cf2b876 100644
--- a/packages/eve/src/runtime/framework-tools/index.ts
+++ b/packages/eve/src/runtime/framework-tools/index.ts
@@ -1,3 +1,4 @@
+import { AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";
import { ASK_QUESTION_TOOL_DEFINITION } from "#runtime/framework-tools/ask-question.js";
import { BASH_TOOL_DEFINITION } from "#runtime/framework-tools/bash.js";
import { GLOB_TOOL_DEFINITION } from "#runtime/framework-tools/glob.js";
@@ -53,5 +54,5 @@ export function getFrameworkToolDefinitions(_config?: {
* as an authoring error rather than silently dropping the request.
*/
export function getAllFrameworkToolNames(): ReadonlySet<string> {
- return new Set(ALL_FRAMEWORK_TOOLS.map((def) => def.name));
+ return new Set([...ALL_FRAMEWORK_TOOLS.map((def) => def.name), AGENT_TOOL_NAME]);
}
diff --git a/packages/eve/test/runtime-agent-graph.test.ts b/packages/eve/test/runtime-agent-graph.test.ts
index b0d7dac0d..801a17f43 100644
--- a/packages/eve/test/runtime-agent-graph.test.ts
+++ b/packages/eve/test/runtime-agent-graph.test.ts
@@ -744,6 +744,34 @@ describe("resolveRuntimeAgentGraph", () => {
]);
});
+ it("accepts the runtime-owned agent tool in disabledFrameworkTools", async () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: {
+ id: TEST_DEFAULT_MODEL_ID,
+ routing: { kind: "gateway", target: "openai" },
+ },
+ name: "weather-agent",
+ },
+ disabledFrameworkTools: ["agent"],
+ });
+
+ const graph = await resolveRuntimeAgentGraph({
+ manifest,
+ moduleMap: {
+ nodes: {
+ [ROOT_COMPILED_AGENT_NODE_ID]: {
+ modules: {},
+ },
+ },
+ },
+ });
+
+ expect(graph.root.agent.disabledFrameworkTools).toContain("agent");
+ });
+
it("combines replacement and disable in one agent", async () => {
const manifest = createCompiledAgentManifest({
agentRoot: "/app/agent",