@cap-js/agents 0.0.0 → 0.9.1

package/srv/handlers/index.js

@@ -0,0 +1,173 @@
+import cds from "@sap/cds"
+import { generateTools, createReadFileTool } from "./tools.js"
+import { buildSystemPrompt } from "./system-prompt.js"
+import buildMiddleware from "../../lib/agents/middleware/index.js"
+import { partsToText } from "../../lib/utils/message-handling.js"
+
+const LOG = cds.log("agents")
+
+/**
+ * Register default event handlers for agent graph building on an @agent service.
+ *
+ * Apps override by registering their own handlers in init() — FIFO semantics
+ * give app handlers (registered first) priority over these defaults.
+ */
+export default function registerDefaultAgentHandlers(srv) {
+  // Default buildTools: generate tools from CDS model + any configured MCP connections.
+  // MCP connections are declared via @agent.mcps annotation on the service:
+  //   @agent.mcps: [{ service: 'MyConnection' }, { service: 'AnotherConnection' }]
+  // Each service name must be defined as a cds.requires entry in package.json.
+  srv.on("buildTools", async () => {
+    const cdsTools = generateTools(srv)
+
+    // ── MCP servers and subagents ────────────────────────────────────────────────────────
+    // Connect to other @mcp services and @agent services
+    function canConnect(s) {
+      return (
+        s.name !== srv.name && (s.protocols?.mcp || s["@mcp"] || s.protocols?.agent || s["@agent"])
+      )
+    }
+
+    const connect =
+      srv.options?.agent?.connect ?? srv.definition["@agent.connect"] ?? cds.env.agents?.connect
+
+    // Allow for providing an mcp or a2a connection with cds.requires only -> no cds.model.services entry
+    // REVISIT: better method?
+    const additionalServices = Object.entries(cds.env.requires).map(([name, s]) => ({
+      name,
+      kind: s?.kind,
+      protocols: { [s?.kind]: true },
+    }))
+
+    const serviceMap = Object.fromEntries(
+      [...additionalServices, ...(cds.model?.services ?? [])].map((s) => [s.name, s]),
+    )
+    const services = Object.values(serviceMap)
+    const selected =
+      connect === "none"
+        ? []
+        : connect === "auto"
+          ? services?.filter(canConnect)
+          : connect === "mcp"
+            ? services?.filter((s) => s.name !== srv.name && (s.protocols?.mcp || s["@mcp"]))
+            : connect === "agent"
+              ? services?.filter((s) => s.name !== srv.name && (s.protocols?.agent || s["@agent"]))
+              : connect?.map((name) => serviceMap[name]).filter(Boolean) || []
+
+    if (selected.length === 0) return cdsTools
+
+    const mcpEntries = []
+    const agentEntries = []
+    for (const s of selected) {
+      if (s.protocols?.agent || s["@agent"]) agentEntries.push(s.name)
+      else if (s.protocols?.mcp || s["@mcp"]) mcpEntries.push(s.name)
+      else LOG.warn(`Agent ${srv.name} could not connect to ${s.name}, missing @mcp or @agent`)
+    }
+
+    const { buildMcpTools } = await import("./mcp-tools.js")
+    const { buildSubAgentTool } = await import("./sub-agent-tools.js")
+
+    const results = await Promise.allSettled([
+      ...mcpEntries.map((e) => buildMcpTools(e.service ?? e)),
+      ...agentEntries.map((e) => buildSubAgentTool(e.service ?? e)),
+    ])
+
+    const extraTools = []
+    for (const r of results) {
+      // MCP connections yield an array of tools; sub-agent connections yield a
+      // single tool. Normalize both so instrumentTools sees a flat tool list.
+      if (r.status === "fulfilled") {
+        if (Array.isArray(r.value)) extraTools.push(...r.value.filter(Boolean))
+        else if (r.value) extraTools.push(r.value)
+      } else LOG.warn("Failed to build external tools:", r.reason?.message ?? r.reason)
+    }
+
+    return [...cdsTools, ...extraTools]
+  })
+
+  srv.after("buildTools", (tools) => tools)
+
+  // Default buildModel: cds.connect.to('llm'), configurable via @agent.llm
+  srv.on("buildModel", async (req) => {
+    const name = srv?.options?.agent?.llm || srv?.definition?.["@agent.llm"] || "llm"
+    let { kind, impl, ...options } = cds.requires[name] ?? {}
+    if (!impl) impl = cds.requires.kinds[kind]?.impl
+    if (!impl) throw new Error("No service implementation found for " + name)
+    const { default: LLMProvider } = await import(impl)
+    return new LLMProvider(name, { ...options, ...req.data })
+  })
+
+  // Default buildSystemPrompt: build from service definition
+  srv.on("buildSystemPrompt", async () => {
+    return buildSystemPrompt(srv)
+  })
+
+  // Default buildMiddleware: quota enforcement, content filtering, agent_actions metric
+  srv.on("buildMiddleware", async (req) => {
+    return buildMiddleware(srv, req.data)
+  })
+
+  // Default buildGraph: if agent dir with AGENTS.md exists → auto-build deep agent.
+  // Otherwise orchestrates sub-events → wires ReAct agent via langchain's createAgent.
+  srv.on("buildGraph", async () => {
+    const { resolveAgentDir, isDeepAgentDir } = await import("../../lib/utils/markdown.js")
+    const agentDir = resolveAgentDir(srv)
+
+    // Auto-built deep agent from AGENTS.md + skills/ convention
+    if (agentDir && isDeepAgentDir(agentDir)) {
+      const { createAutoDeepAgent } = await import("../../lib/agents/markdown/deep-agent.js")
+      return createAutoDeepAgent(srv, agentDir)
+    }
+
+    // Standard ReAct agent via langchain's createAgent
+    const { createAgent } = await import("langchain")
+    const { CdsCheckpointSaver } =
+      await import("../../lib/protocol/persistence/checkpoint-saver.js")
+    const { GraphExecutor } = await import("./graph-executor.js")
+
+    const tools = await srv.send("buildTools")
+
+    // File-IO: add a read_file tool that resolves context at invocation time.
+    // cds.context["agent.context.id"] and user.id are set by GraphExecutor before invoke.
+    if (cds.env.agents?.fileIO?.enabled) {
+      const { CdsFileStore } = await import("../../lib/protocol/persistence/file-store.js")
+      const fileStore = new CdsFileStore()
+      const readFileTool = createReadFileTool(fileStore)
+      tools.push(readFileTool)
+    }
+
+    let model = await srv.send("buildModel", { tools })
+
+    const systemPrompt = await srv.send("buildSystemPrompt")
+    const middleware = await srv.send("buildMiddleware", { tools, model })
+
+    const checkpointer = new CdsCheckpointSaver()
+
+    const agent = createAgent({
+      model,
+      tools,
+      systemPrompt,
+      middleware,
+      checkpointer,
+    })
+
+    return new GraphExecutor(agent, srv, {
+      checkpointer: false, // already set on createAgent
+      // Standard ReAct agents have no built-in recursionLimit default (LangGraph's
+      // fallback is 25, which is too low for multi-tool tasks). Deep agents go through
+      // langgraph-executor-srv.js which passes no recursionLimit → deepagents' 10000 wins.
+      recursionLimit: cds.env.agents?.recursionLimit ?? 100,
+      inputMapper: async (requestContext) => {
+        const { HumanMessage } = await import("@langchain/core/messages")
+        const text = partsToText(requestContext.userMessage?.parts)
+
+        // Append file manifest injected by GraphExecutor.execute() (fileIO path)
+        const fullText = requestContext._fileManifest
+          ? `${text}\n${requestContext._fileManifest}`
+          : text
+
+        return { messages: [new HumanMessage(fullText)] }
+      },
+    })
+  })
+}

package/srv/handlers/mcp-tools.js

@@ -0,0 +1,159 @@
+import cds from "@sap/cds"
+import { MultiServerMCPClient } from "@langchain/mcp-adapters"
+import { generateTools } from "./tools.js"
+import { toolName } from "../../lib/utils/utils.js"
+
+const LOG = cds.log("agents:mcp")
+
+/**
+ * Resolve URL and HTTP headers for a BTP destination using the Cloud SDK.
+ * Passes the incoming user JWT for OAuth2UserTokenExchange destinations.
+ * Falls back to CAP's authTokens if Cloud SDK resolution fails.
+ *
+ * @param {string} destinationName
+ * @param {object|string} dest - raw CAP destination value (for fallback)
+ * @param {string|null} localUrl - URL already known from CAP (fallback if Cloud SDK has none)
+ * @returns {Promise<{ url: string|null, headers: Record<string, string> }>}
+ */
+async function resolveDestination(destinationName, dest, localUrl) {
+  try {
+    const { getDestination, buildHeadersForDestination, retrieveJwt } =
+      await import("@sap-cloud-sdk/connectivity")
+    const jwt = retrieveJwt(cds.context?.http?.req)
+    const resolvedDest = await getDestination({ destinationName, jwt })
+    if (!resolvedDest) return { url: localUrl, headers: {} }
+
+    const rawHeaders = await buildHeadersForDestination(resolvedDest)
+    // Cloud SDK returns lowercase header keys (e.g. "authorization") —
+    // normalize to title-case so HTTP clients handle them correctly.
+    const headers = Object.fromEntries(
+      Object.entries(rawHeaders).map(([k, v]) => [
+        k.replace(/(^|-)(.)/g, (_, sep, c) => sep + c.toUpperCase()),
+        v,
+      ]),
+    )
+    return { url: resolvedDest.url ?? localUrl, headers }
+  } catch (err) {
+    LOG.warn(
+      `Could not resolve destination "${destinationName}" via Cloud SDK, falling back to CAP destination: ${err.message}`,
+    )
+    const token = typeof dest === "object" ? dest?.authTokens?.[0]?.value : null
+    return { url: localUrl, headers: token ? { Authorization: `Bearer ${token}` } : {} }
+  }
+}
+
+/**
+ * Wrap MCP tool invocations to convert errors into plain string results.
+ * deepagents' wrapToolCall middleware marks errors thrown inside it as
+ * "middleware errors", which LangChain's ToolNode re-throws rather than
+ * converting to a ToolMessage (see ToolNode.js: isMiddlewareError check).
+ * MCP tool schema validation errors therefore crash the graph instead of
+ * being fed back to the LLM as recoverable feedback.
+ */
+function wrapToolsWithErrorHandling(tools, serviceName) {
+  return tools.map((tool) => {
+    const original = tool.invoke.bind(tool)
+    tool.invoke = async (args, config) => {
+      try {
+        return await original(args, config)
+      } catch (err) {
+        LOG.warn(`MCP tool "${tool.name}" error: ${err.message}`, { service: serviceName })
+        return `Error: ${err.message}`
+      }
+    }
+    return tool
+  })
+}
+
+export async function buildMcpToolsLocally(serviceName) {
+  const srv = cds.services[serviceName]
+  const tools = generateTools(srv)
+  const prefix = toolName(`${serviceName}_`)
+  for (const tool of tools) tool.name = `${prefix}${tool.name}`
+
+  LOG.info(
+    `Got ${tools.length} MCP tools from ${serviceName}: ${tools.map((t) => t.name).join(", ")}`,
+  )
+  return tools
+}
+
+/**
+ * Build LangChain tools from a CAP MCP connection.
+ * Resolves the destination URL and auth headers, connects to the MCP server,
+ * and returns the tools wrapped with error handling for use in agent graphs.
+ *
+ * @param {string} serviceName - cds.requires service key
+ * @returns {Promise<import("@langchain/core/tools").StructuredTool[]>}
+ */
+export async function buildMcpToolsFromConnection(serviceName) {
+  let endpoints = cds.service.endpoints4({
+    name: serviceName,
+    definition: cds.model.services[serviceName],
+  })
+  endpoints = Object.fromEntries(endpoints.map((o) => [o.kind, o.path]))
+  const { credentials, kind } = cds.requires[serviceName]
+
+  // dest is either a string (BTP destination name) or an object { name, url, ... }
+  const destinationName = typeof credentials === "string" ? credentials : credentials?.name
+  const localUrl =
+    typeof credentials === "string"
+      ? null
+      : kind === undefined
+        ? credentials?.url?.replace("undefined", endpoints?.mcp)
+        : kind !== "mcp" && endpoints?.[kind]
+          ? credentials?.url.replace(endpoints[kind], endpoints.mcp)
+          : credentials?.url
+
+  if (!localUrl && !destinationName) {
+    throw new Error(
+      `[mcp-tools] Could not resolve URL or destination name for service "${serviceName}". Check cds.requires config.`,
+    )
+  }
+
+  // REVISIT: url resolution at runtime, potentially using RemoteService?
+  const { url } = destinationName
+    ? await resolveDestination(destinationName, credentials, localUrl)
+    : { url: localUrl }
+
+  if (!url) {
+    throw new Error(
+      `[mcp-tools] Could not resolve URL for service "${serviceName}" after destination lookup.`,
+    )
+  }
+
+  const mcpUrl = url.replace(/\/$/, "")
+  LOG.info(`Connecting to MCP server at ${mcpUrl}`)
+
+  const resolveHeaders = async () => {
+    if (destinationName) {
+      const { headers } = await resolveDestination(destinationName, credentials, url)
+      LOG.debug(`Resolved destination "${destinationName}"`, { headerKeys: Object.keys(headers) })
+      return headers
+    }
+    const token = credentials?.authTokens?.[0]?.value
+    return token ? { Authorization: `Bearer ${token}` } : {}
+  }
+
+  const client = new MultiServerMCPClient({
+    mcpServers: {
+      [serviceName]: { url: mcpUrl },
+    },
+    beforeToolCall: async () => ({ headers: await resolveHeaders() }),
+  })
+
+  const tools = await client.getTools()
+  const prefix = toolName(`${serviceName}_`)
+  for (const tool of tools) tool.name = `${prefix}${tool.name}`
+
+  LOG.info(
+    `Got ${tools.length} MCP tools from ${serviceName}: ${tools.map((t) => t.name).join(", ")}`,
+  )
+
+  return wrapToolsWithErrorHandling(tools, serviceName)
+}
+
+export async function buildMcpTools(serviceName) {
+  return cds.requires[serviceName]?.credentials
+    ? buildMcpToolsFromConnection(serviceName)
+    : buildMcpToolsLocally(serviceName)
+}

package/srv/handlers/sub-agent-tools.js

@@ -0,0 +1,314 @@
+import cds from "@sap/cds"
+import { tool } from "@langchain/core/tools"
+import { z } from "zod"
+import { LangGraphExecutor } from "../langgraph-executor-srv.js"
+import { toolName } from "../../lib/utils/utils.js"
+
+const LOG = cds.log("agents:sub-agents")
+
+/**
+ * Extract text and file parts from an A2A response (task or message).
+ */
+function extractResult(result) {
+  if (!result) return { text: "No response from agent.", files: [] }
+
+  const text = []
+  const files = []
+
+  const processParts = (parts = []) => {
+    for (const part of parts) {
+      if (part.kind === "text") text.push(part.text)
+      else if (part.kind === "file") files.push(part)
+    }
+  }
+
+  if (result.kind === "task") {
+    processParts(result.status?.message?.parts)
+    for (const artifact of result.artifacts || []) processParts(artifact.parts)
+    if (text.length === 0 && files.length === 0) {
+      return { text: `Task ${result.id}: ${result.status?.state || "unknown"}`, files: [] }
+    }
+  } else if (result.kind === "message") {
+    processParts(result.parts)
+  } else {
+    return { text: JSON.stringify(result), files: [] }
+  }
+
+  return { text: text.join("\n") || "No response.", files }
+}
+
+/**
+ * Build the tool description from an agent card (or agent-card-like object).
+ */
+function toolDescription(card) {
+  const skills = card.skills?.map((s) => `- ${s.name}: ${s.description}`).join("\n") || ""
+  return (
+    `Delegate to the "${card.name}" agent. ${card.description || ""}` +
+    (skills ? `\n\nSkills:\n${skills}` : "")
+  )
+}
+
+/**
+ * Format an extracted { text, files } pair into the string a tool returns.
+ *
+ * FileParts are serialized inline as {"kind":"file",...} JSON so the executor's
+ * file-collection loop (graph-executor.js) picks them up and re-publishes them
+ * as A2A artifacts, plus a human-readable manifest note for the model.
+ */
+function formatToolResult({ text, files }) {
+  if (!files || files.length === 0) return text
+  const fileJson = files.map((f) => JSON.stringify({ kind: "file", file: f.file })).join("\n")
+  const manifest = files
+    .filter((f) => f.file?.bytes)
+    .map((f) => `/uploads/${f.file.name} (${f.file.mimeType})`)
+  const manifestNote = manifest.length
+    ? `\n[Files from downstream agent: ${manifest.join(", ")}]`
+    : ""
+  return `${text}${manifestNote}\n${fileJson}`
+}
+
+/**
+ * Wrap an A2A client as a LangChain tool the agent can call.
+ */
+function createA2ATool(client, agentCard) {
+  return tool(
+    async ({ message }) => {
+      try {
+        const result = await client.sendMessage({
+          message: {
+            kind: "message",
+            role: "user",
+            messageId: cds.utils.uuid(),
+            parts: [{ kind: "text", text: message }],
+          },
+        })
+        return formatToolResult(extractResult(result))
+      } catch (err) {
+        LOG.warn("Sub-agent tool error", { agent: agentCard.name, error: err.message })
+        return `Error communicating with ${agentCard.name}: ${err.message}`
+      }
+    },
+    {
+      name: toolName(agentCard.name),
+      description: toolDescription(agentCard),
+      schema: z.object({
+        message: z.string().describe("The request to send to this agent"),
+      }),
+    },
+  )
+}
+
+export async function buildSubAgentToolLocally(serviceName) {
+  const srv = cds.services[serviceName]
+  if (!srv) throw new Error(`[sub-agents] No local service "${serviceName}" found.`)
+
+  const executor = LangGraphExecutor.for(srv)
+
+  const { generateAgentCard } = await import("../../lib/protocol/agent-card.js")
+  const agentCard = generateAgentCard(srv)
+  LOG.info(`Wired local sub-agent "${agentCard.name}" (${serviceName})`)
+
+  const { RequestContext, DefaultExecutionEventBus } = await import("@a2a-js/sdk/server")
+
+  return tool(
+    async ({ message }) => {
+      const taskId = cds.utils.uuid()
+      const contextId = cds.utils.uuid()
+
+      // Drive the local executor directly (no HTTP). Collect published events
+      // into a synthetic task so we can reuse extractResult for text + files.
+      const eventBus = new DefaultExecutionEventBus()
+
+      // The terminal status message and the "response" text artifact carry the
+      // final answer; file-* artifacts carry downstream FileParts. Accumulate
+      // the latest of each so partial/streamed updates are superseded.
+      let statusText = null
+      let responseText = null
+      let failed = null
+      const files = []
+
+      eventBus.on("event", (event) => {
+        if (event.kind === "status-update") {
+          const state = event.status?.state
+          const text = event.status?.message?.parts
+            ?.filter((p) => p.kind === "text")
+            .map((p) => p.text)
+            .join("\n")
+          if (text) statusText = text
+          if (state === "failed") failed = text || "Sub-agent execution failed."
+        } else if (event.kind === "artifact-update") {
+          const parts = event.artifact?.parts || []
+          if (event.artifact?.artifactId === "response") {
+            // append:false replaces; append:true accumulates streamed tokens.
+            const text = parts
+              .filter((p) => p.kind === "text")
+              .map((p) => p.text)
+              .join("")
+            if (text) responseText = event.append ? (responseText || "") + text : text
+          }
+          for (const p of parts) if (p.kind === "file") files.push(p)
+        }
+      })
+
+      const done = new Promise((resolve) => eventBus.once("finished", resolve))
+
+      const requestContext = new RequestContext(
+        {
+          kind: "message",
+          role: "user",
+          messageId: cds.utils.uuid(),
+          taskId,
+          contextId,
+          parts: [{ kind: "text", text: message }],
+        },
+        taskId,
+        contextId,
+      )
+
+      try {
+        // Run the sub-agent detached from the calling agent, in its own root
+        // context and transaction (cds.spawn creates + commits a fresh tx). A
+        // shared transaction breaks the stream.
+        await new Promise((resolve, reject) => {
+          cds
+            .spawn({ user: cds.context?.user, tenant: cds.context?.tenant }, async () => {
+              await executor.execute(requestContext, eventBus)
+              await done
+            })
+            .on("succeeded", resolve)
+            .on("failed", reject)
+        })
+      } catch (err) {
+        LOG.warn("Local sub-agent tool error", { agent: agentCard.name, error: err.message })
+        return `Error running ${agentCard.name}: ${err.message}`
+      }
+
+      if (failed) return `Error running ${agentCard.name}: ${failed}`
+
+      const text = responseText || statusText || "No response."
+      return formatToolResult({ text, files })
+    },
+    {
+      name: toolName(agentCard.name),
+      description: toolDescription(agentCard),
+      schema: z.object({
+        message: z.string().describe("The request to send to this agent"),
+      }),
+    },
+  )
+}
+
+export async function buildSubAgentToolFromConnection(serviceName) {
+  let endpoints = cds.service.endpoints4({
+    name: serviceName,
+    definition: cds.model.services[serviceName],
+  })
+  endpoints = Object.fromEntries(endpoints.map((o) => [o.kind, o.path]))
+  const { credentials, kind } = cds.requires[serviceName]
+
+  const destinationName = typeof credentials === "string" ? credentials : credentials?.name
+  const localUrl =
+    typeof credentials === "string"
+      ? null
+      : kind === undefined
+        ? credentials?.url?.replace("undefined", endpoints?.agent)
+        : kind !== "agent" && endpoints?.[kind]
+          ? credentials?.url.replace(endpoints[kind], endpoints.agent)
+          : credentials?.url
+
+  if (!localUrl && !destinationName) {
+    throw new Error(
+      `[sub-agents] Could not resolve URL or destination name for service "${serviceName}". Check cds.requires config.`,
+    )
+  }
+
+  const resolveHeaders = destinationName
+    ? async () => {
+        try {
+          const { getDestination, buildHeadersForDestination, retrieveJwt } =
+            await import("@sap-cloud-sdk/connectivity")
+          const jwt = retrieveJwt(cds.context?.http?.req)
+          const resolvedDest = await getDestination({ destinationName, jwt })
+          const rawHeaders = await buildHeadersForDestination(resolvedDest)
+          return Object.fromEntries(
+            Object.entries(rawHeaders).map(([k, v]) => [
+              k.replace(/(^|-)(.)/g, (_, sep, c) => sep + c.toUpperCase()),
+              v,
+            ]),
+          )
+        } catch (err) {
+          LOG.warn(
+            `Could not resolve destination "${destinationName}" via Cloud SDK, falling back: ${err.message}`,
+          )
+          const token = typeof credentials === "object" ? credentials?.authTokens?.[0]?.value : null
+          return token ? { Authorization: `Bearer ${token}` } : {}
+        }
+      }
+    : async () => {
+        const token = credentials?.authTokens?.[0]?.value
+        return token ? { Authorization: `Bearer ${token}` } : {}
+      }
+
+  // Resolve URL once at build time; headers are resolved fresh on every request.
+  let agentBaseUrl = localUrl
+  if (destinationName) {
+    try {
+      const { getDestination, retrieveJwt } = await import("@sap-cloud-sdk/connectivity")
+      const jwt = retrieveJwt(cds.context?.http?.req)
+      const resolvedDest = await getDestination({ destinationName, jwt })
+      if (resolvedDest?.url) agentBaseUrl = resolvedDest.url
+    } catch (err) {
+      LOG.warn(
+        `Could not resolve destination URL for "${destinationName}", using localUrl: ${err.message}`,
+      )
+    }
+  }
+
+  if (!agentBaseUrl) {
+    throw new Error(
+      `[sub-agents] Could not resolve URL for service "${serviceName}" after destination lookup.`,
+    )
+  }
+
+  const base = agentBaseUrl.replace(/\/$/, "")
+  LOG.info(`Connecting to sub-agent at ${base}`)
+
+  // revisit: a2a agents may be tenant specific, card per tenant?
+  const initialHeaders = await resolveHeaders()
+  const cardUrl = `${base}/.well-known/agent-card.json`
+  const cardRes = await fetch(cardUrl, {
+    headers: { Accept: "application/json", ...initialHeaders },
+  })
+  if (!cardRes.ok) {
+    throw new Error(
+      `[sub-agents] Agent card fetch failed for "${serviceName}" at ${cardUrl}: HTTP ${cardRes.status}`,
+    )
+  }
+  const agentCard = await cardRes.json()
+  LOG.info(`Connected to sub-agent "${agentCard.name}" (${serviceName})`)
+
+  const { ClientFactory, ClientFactoryOptions, JsonRpcTransportFactory, RestTransportFactory } =
+    await import("@a2a-js/sdk/client")
+
+  const customFetch = async (url, init = {}) => {
+    const headers = await resolveHeaders()
+    return fetch(url, { ...init, headers: { ...headers, ...(init.headers || {}) } })
+  }
+  const factory = new ClientFactory(
+    ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+      transports: [
+        new JsonRpcTransportFactory({ fetchImpl: customFetch }),
+        new RestTransportFactory({ fetchImpl: customFetch }),
+      ],
+    }),
+  )
+  const client = await factory.createFromAgentCard(agentCard)
+
+  return createA2ATool(client, agentCard)
+}
+
+export function buildSubAgentTool(serviceName) {
+  return cds.requires[serviceName]?.credentials
+    ? buildSubAgentToolFromConnection(serviceName)
+    : buildSubAgentToolLocally(serviceName)
+}

package/srv/handlers/system-prompt.js

@@ -0,0 +1,25 @@
+import cds from "@sap/cds"
+import { getDescription } from "../../lib/utils/utils.js"
+
+export function buildSystemPrompt(srv) {
+  const serviceDesc = getDescription(srv.definition) || `Service ${srv.name}`
+
+  return [
+    `You are an AI assistant for the "${srv.name}" service.`,
+    serviceDesc,
+    "",
+    "Always use the provided tools to answer questions - do not make up data.",
+    "Use the `describe` tool to get information about the service's entities and actions if needed.",
+    "Use the `query` tool to read data from entities.",
+    cds.env.agents?.per_action_tool !== false
+      ? "Call action and function tools directly by name."
+      : "Use the `call` tool to invoke actions and functions.",
+    ...(cds.env.agents?.fileIO?.enabled
+      ? [
+          "When the user's message contains '[Uploaded files: ...]', use the `read_file` tool to read each listed file before answering.",
+          "Use `emit_file_part` to return files in your response.",
+        ]
+      : []),
+    "Be concise and helpful.",
+  ].join("\n")
+}