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.mdnew file mode 100644index 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.mdindex 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 tooldiff --git a/packages/eve/src/compiler/normalize-subagent.ts b/packages/eve/src/compiler/normalize-subagent.tsindex 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.tsindex 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.tsindex 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.tsindex 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-tooexport {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.tsindex 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.tsindex 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.tsindex 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([{