Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): resolve remote agent url at runtime via function (#670)

Casey Gowrief83d47dd29e0
diff --git a/.changeset/remote-agent-runtime-url.md b/.changeset/remote-agent-runtime-url.md
new file mode 100644
index 000000000..6b560eca1
--- /dev/null
+++ b/.changeset/remote-agent-runtime-url.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+`defineRemoteAgent` now accepts a function for `url`, resolved at runtime instead of baked at compile time. Return a `string` (or `Promise<string>`) from `() => process.env.MY_SERVICE_URL` to target an endpoint supplied by a runtime env var, known only once the deployment runs.
diff --git a/docs/guides/remote-agents.md b/docs/guides/remote-agents.md
index bc68da496..dd3c95c9b 100644
--- a/docs/guides/remote-agents.md
+++ b/docs/guides/remote-agents.md
@@ -20,14 +20,29 @@ export default defineRemoteAgent({
`defineRemoteAgent` accepts:
-| Parameter | Type | Required | Default | Description |
-| -------------- | ------------------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url` | `string` | Yes | n/a | Base URL of the remote eve deployment to call. |
-| `description` | `string` | Yes | n/a | Model-visible delegation description. |
-| `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
-| `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
-| `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
-| `outputSchema` | `StandardSchema \| JSON Schema` | No | none | Structured return type the caller requires. Lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema. |
+| Parameter | Type | Required | Default | Description |
+| -------------- | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
+| `description` | `string` | Yes | n/a | Model-visible delegation description. |
+| `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
+| `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
+| `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
+| `outputSchema` | `StandardSchema \| JSON Schema` | No | none | Structured return type the caller requires. Lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema. |
+
+## Runtime URLs
+
+A string `url` is read at compile time and frozen into the build. When the target comes from a runtime env var — known only once the deployment runs — pass a function instead. eve calls it when it resolves the agent graph at runtime, so it can read `process.env`:
+
+```ts title="agent/subagents/weather.ts"
+import { defineRemoteAgent } from "eve";
+
+export default defineRemoteAgent({
+ url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
+ description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
+});
+```
+
+The function may be async and must return a non-empty string. `auth` and `headers` are resolved at runtime the same way.
## The lowered tool
diff --git a/packages/eve/src/compiler/normalize-subagent.ts b/packages/eve/src/compiler/normalize-subagent.ts
index 85c477a50..11458ffdf 100644
--- a/packages/eve/src/compiler/normalize-subagent.ts
+++ b/packages/eve/src/compiler/normalize-subagent.ts
@@ -229,7 +229,7 @@ function compileRemoteAgent(input: {
`Expected the remote agent config export "${configModule.exportName ?? "default"}" from "${moduleSource.logicalPath}" to match the public eve shape.`,
);
- return {
+ const node = {
...moduleSource,
description: definition.description,
entryPath: input.source.entryPath,
@@ -238,8 +238,10 @@ function compileRemoteAgent(input: {
outputSchema: definition.outputSchema,
path: definition.path,
rootPath: input.source.rootPath,
- url: definition.url,
};
+
+ // A function `url` is deferred, so the compiled node omits it entirely.
+ return definition.url === undefined ? node : { ...node, url: definition.url };
}
function createSubagentConfigModuleSourceRef(
@@ -288,7 +290,7 @@ function normalizeRemoteAgentDefinition(
readonly description: string;
readonly outputSchema?: JsonObject;
readonly path: string;
- readonly url: string;
+ readonly url?: string;
} {
const record = expectObjectRecord(value, message);
expectOnlyKnownKeys(
@@ -311,7 +313,8 @@ function normalizeRemoteAgentDefinition(
record.path === undefined
? EVE_CREATE_SESSION_ROUTE_PATH
: expectString(record.path, message),
- url: expectString(record.url, message),
+ // A function `url` is resolved at runtime, not baked into the manifest.
+ url: typeof record.url === "function" ? undefined : expectString(record.url, message),
};
}
diff --git a/packages/eve/src/compiler/remote-agent-node.ts b/packages/eve/src/compiler/remote-agent-node.ts
index dafae0990..b22c08014 100644
--- a/packages/eve/src/compiler/remote-agent-node.ts
+++ b/packages/eve/src/compiler/remote-agent-node.ts
@@ -19,7 +19,8 @@ export type CompiledRemoteAgentNode = Readonly<
outputSchema?: JsonObject;
path: string;
rootPath: string;
- url: string;
+ // Absent when the definition's `url` is a function the runtime resolves.
+ url?: string;
}
>;
@@ -39,6 +40,6 @@ export const compiledRemoteAgentNodeSchema: z.ZodType<CompiledRemoteAgentNode> =
rootPath: z.string(),
sourceId: z.string(),
sourceKind: z.literal("module"),
- url: z.string(),
+ url: z.string().optional(),
})
.strict();
diff --git a/packages/eve/src/public/definitions/remote-agent.ts b/packages/eve/src/public/definitions/remote-agent.ts
index d928d3f1a..dadbbdb85 100644
--- a/packages/eve/src/public/definitions/remote-agent.ts
+++ b/packages/eve/src/public/definitions/remote-agent.ts
@@ -4,6 +4,14 @@ import type { OutboundAuthFn } from "#public/agents/auth.js";
import { EVE_CREATE_SESSION_ROUTE_PATH } from "#protocol/routes.js";
import type { JsonObject } from "#shared/json.js";
+/**
+ * Base URL of a remote eve deployment, either a static string or a function
+ * resolved at runtime. Use the function form to read `process.env` for a URL
+ * known only once the deployment runs. A string is baked into the compiled
+ * manifest; a function is invoked when the runtime resolves the agent graph.
+ */
+export type RemoteAgentUrl = string | (() => string | Promise<string>);
+
/**
* Public definition for a remote eve agent. The compiler lowers it to a
* subagent tool.
@@ -29,9 +37,11 @@ export interface RemoteAgentDefinition {
*/
readonly path: string;
/**
- * Base URL of the remote eve deployment to call.
+ * Base URL of the remote eve deployment to call. Accepts a static string
+ * (baked at compile time) or a function resolved at runtime — use the
+ * function form to read a URL from `process.env`.
*/
- readonly url: string;
+ readonly url: RemoteAgentUrl;
}
/**
diff --git a/packages/eve/src/public/index.ts b/packages/eve/src/public/index.ts
index 04f0536a7..89c12df7f 100644
--- a/packages/eve/src/public/index.ts
+++ b/packages/eve/src/public/index.ts
@@ -19,5 +19,6 @@ export type { DynamicResolveContext, DynamicSentinel } from "#shared/dynamic-too
export {
type RemoteAgentDefinition,
type RemoteAgentDefinitionInput,
+ type RemoteAgentUrl,
defineRemoteAgent,
} from "#public/definitions/remote-agent.js";
diff --git a/packages/eve/src/runtime/resolve-agent-graph.ts b/packages/eve/src/runtime/resolve-agent-graph.ts
index a1f8c0b3b..9d11ea9c9 100644
--- a/packages/eve/src/runtime/resolve-agent-graph.ts
+++ b/packages/eve/src/runtime/resolve-agent-graph.ts
@@ -369,7 +369,11 @@ async function resolveRuntimeRemoteAgent(input: {
path: input.sourceRef.path,
sourceId: input.sourceRef.sourceId,
sourceKind: "module",
- url: input.sourceRef.url,
+ url: await resolveRemoteAgentUrl({
+ bakedUrl: input.sourceRef.url,
+ logicalPath: input.sourceRef.logicalPath,
+ resolvedUrl: resolvedRecord.url,
+ }),
};
if (typeof resolvedRecord.auth === "function") {
@@ -385,6 +389,28 @@ async function resolveRuntimeRemoteAgent(input: {
return resolvedRemoteAgent;
}
+async function resolveRemoteAgentUrl(input: {
+ readonly bakedUrl: string | undefined;
+ readonly logicalPath: string;
+ readonly resolvedUrl: unknown;
+}): Promise<string> {
+ if (typeof input.resolvedUrl === "function") {
+ const resolved = await (input.resolvedUrl as () => unknown)();
+ if (typeof resolved !== "string" || resolved.length === 0) {
+ throw new Error(
+ `Remote agent "${input.logicalPath}" url function must return a non-empty string.`,
+ );
+ }
+ return resolved;
+ }
+
+ const url = input.bakedUrl ?? (typeof input.resolvedUrl === "string" ? input.resolvedUrl : "");
+ if (url.length === 0) {
+ throw new Error(`Remote agent "${input.logicalPath}" is missing a url.`);
+ }
+ return url;
+}
+
function resolveRemoteAgentHeaders(value: unknown): HeadersValue | undefined {
if (value === undefined) {
return undefined;
diff --git a/packages/eve/test/runtime-agent-graph.test.ts b/packages/eve/test/runtime-agent-graph.test.ts
index 6a92fc71f..b0d7dac0d 100644
--- a/packages/eve/test/runtime-agent-graph.test.ts
+++ b/packages/eve/test/runtime-agent-graph.test.ts
@@ -504,7 +504,6 @@ describe("resolveRuntimeAgentGraph", () => {
rootPath: agentRoot,
sourceId: "subagents/weather.ts",
sourceKind: "module",
- url: "https://weather.example.com",
},
],
subagentEdges: [
@@ -538,7 +537,7 @@ describe("resolveRuntimeAgentGraph", () => {
description: "Answer weather questions remotely.",
kind: "remote",
path: "/eve/v1/session",
- url: "https://weather.example.com",
+ url: () => "https://weather.example.com",
},
},
},
@@ -589,6 +588,59 @@ describe("resolveRuntimeAgentGraph", () => {
});
});
+ it("resolves a remote subagent url function from process.env at runtime", async () => {
+ vi.stubEnv("WEATHER_AGENT_URL", "https://weather.internal.vercel.app");
+ const agentRoot = "/app/agent";
+ const manifest = createCompiledAgentManifest({
+ agentRoot,
+ appRoot: "/app",
+ config: {
+ model: {
+ id: TEST_DEFAULT_MODEL_ID,
+ routing: { kind: "gateway", target: "openai" },
+ },
+ name: "router",
+ },
+ remoteAgents: [
+ {
+ description: "Answer weather questions remotely.",
+ entryPath: `${agentRoot}/subagents/weather.ts`,
+ logicalPath: "subagents/weather.ts",
+ name: "weather",
+ nodeId: "subagents/weather.ts",
+ path: "/eve/v1/session",
+ rootPath: agentRoot,
+ sourceId: "subagents/weather.ts",
+ sourceKind: "module",
+ },
+ ],
+ });
+ const graph = await resolveRuntimeAgentGraph({
+ manifest,
+ moduleMap: {
+ nodes: {
+ [ROOT_COMPILED_AGENT_NODE_ID]: {
+ modules: {
+ "subagents/weather.ts": {
+ default: {
+ description: "Answer weather questions remotely.",
+ kind: "remote",
+ path: "/eve/v1/session",
+ url: () => process.env.WEATHER_AGENT_URL,
+ },
+ },
+ },
+ },
+ },
+ },
+ });
+
+ expect(graph.root.subagentRegistry.subagentsByName.get("weather")?.definition).toMatchObject({
+ kind: "remote",
+ url: "https://weather.internal.vercel.app",
+ });
+ });
+
it("lets an authored tool replace a framework tool by name collision", async () => {
const manifest = createCompiledAgentManifest({
agentRoot: "/app/agent",
diff --git a/packages/eve/test/scenarios/compile-agent.scenario.test.ts b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
index 61bf95ed3..3d9973b62 100644
--- a/packages/eve/test/scenarios/compile-agent.scenario.test.ts
+++ b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
@@ -1078,7 +1078,7 @@ describe("compileAgent", () => {
"export default {",
' kind: "remote",',
' description: "Answer weather questions remotely.",',
- ' url: "https://weather.example.com",',
+ ' url: () => process.env.WEATHER_AGENT_URL ?? "https://weather.example.com",',
"};",
"",
].join("\n"),
@@ -1119,9 +1119,10 @@ describe("compileAgent", () => {
nodeId: "subagents/weather.ts",
path: "/eve/v1/session",
sourceId: "subagents/weather.ts",
- url: "https://weather.example.com",
},
]);
+ // A function `url` is resolved at runtime, so nothing is baked here.
+ expect(result.manifest.remoteAgents[0]).not.toHaveProperty("url");
expect(result.manifest.subagents).toHaveLength(1);
expect(result.manifest.subagents[0]?.agent.remoteAgents).toMatchObject([
{