@cap-js/agents 0.9.3 → 0.9.5

package/srv/handlers/index.js

@@ -67,7 +67,7 @@ export default function registerDefaultAgentHandlers(srv) {
     }
 
     const { buildMcpTools } = await import("./mcp-tools.js")
-    const { buildSubAgentTool } = await import("./sub-agent-tools.js")
+    const { buildSubAgentTool } = await import("./subagent-tools.js")
 
     const results = await Promise.allSettled([
       ...mcpEntries.map((e) => buildMcpTools(e.service ?? e)),
@@ -76,7 +76,7 @@ export default function registerDefaultAgentHandlers(srv) {
 
     const extraTools = []
     for (const r of results) {
-      // MCP connections yield an array of tools; sub-agent connections yield a
+      // MCP connections yield an array of tools; subagent 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))
@@ -92,7 +92,8 @@ export default function registerDefaultAgentHandlers(srv) {
   // 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] ?? {}
+    const options = cds.requires[name] ?? {}
+    let { kind, impl } = options
     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)

package/srv/handlers/mcp-tools.js

@@ -101,7 +101,7 @@ export async function buildMcpToolsFromConnection(serviceName) {
 
   const path = typeof credentials === "object" ? credentials?.path : null
   const mcpUrl = url.replace(/\/$/, "") + (path ? `/${path.replace(/^\//, "")}` : "")
-  LOG.info(`Connecting to MCP server at ${mcpUrl}`)
+  LOG.info(`Connecting to MCP service ${serviceName}`, { at: mcpUrl })
 
   const resolveHeaders = async () => {
     if (destinationName) {
@@ -113,7 +113,8 @@ export async function buildMcpToolsFromConnection(serviceName) {
     return token ? { Authorization: `Bearer ${token}` } : {}
   }
 
-  return { _mcpDynamic: true, mcpUrl, serviceName, resolveHeaders }
+  const toolFilter = cds.requires[serviceName]?.mcp?.tools
+  return { _mcpDynamic: true, mcpUrl, serviceName, resolveHeaders, toolFilter }
 }
 
 export async function buildMcpTools(serviceName) {

package/srv/handlers/{sub-agent-tools.js → subagent-tools.js}

@@ -1,11 +1,16 @@
 import cds from "@sap/cds"
 import { tool } from "@langchain/core/tools"
 import { z } from "zod"
+import { getTracer } from "../../lib/telemetry/metrics.js"
 import { LangGraphExecutor } from "../langgraph-executor-srv.js"
 import { short, toolName } from "../../lib/utils/utils.js"
 
-const LOG = cds.log("agents:sub-agents")
+const LOG = cds.log("agents:a2a|agents|subagents|a2a")
 
+const TRUNCATE = cds.env.agents?.truncate || 111
+const truncated = (msg) => (msg?.length > TRUNCATE ? msg.slice(0, TRUNCATE) + "..." : msg)
+
+import { inspect } from "util"
 /**
  * Extract text and file parts from an A2A response (task or message).
  */
@@ -15,7 +20,7 @@ function extractResult(result) {
   const text = []
   const files = []
 
-  const processParts = (parts = []) => {
+  const processParts = (parts) => {
     for (const part of parts) {
       if (part.kind === "text") text.push(part.text)
       else if (part.kind === "file") files.push(part)
@@ -23,8 +28,11 @@ function extractResult(result) {
   }
 
   if (result.kind === "task") {
-    processParts(result.status?.message?.parts)
-    for (const artifact of result.artifacts || []) processParts(artifact.parts)
+    if (result.artifacts)
+      for (let artifact of result.artifacts) {
+        if (!artifact.artifactId.startsWith("thinking")) processParts(artifact.parts)
+      }
+    else if (result.status?.message) processParts(result.status.message.parts)
     if (text.length === 0 && files.length === 0) {
       return { text: `Task ${result.id}: ${result.status?.state || "unknown"}`, files: [] }
     }
@@ -71,21 +79,33 @@ function formatToolResult({ text, files }) {
  * Wrap an A2A client as a LangChain tool the agent can call.
  */
 function createA2ATool(client, agentCard) {
+  const subagent = agentCard.name
   return tool(
     async ({ message }) => {
       try {
+        const messageId = cds.utils.uuid()
+        LOG.info(`Sending message to ${subagent}`, { messageId }, "\n\n" + message + "\n")
         const result = await client.sendMessage({
           message: {
             kind: "message",
             role: "user",
-            messageId: cds.utils.uuid(),
+            messageId,
             parts: [{ kind: "text", text: message }],
           },
         })
-        return formatToolResult(extractResult(result))
+        if (LOG._debug)
+          LOG.trace(`Raw results from ${subagent}`, inspect(result, { depth: null, colors: true }))
+        let response = formatToolResult(extractResult(result))
+        if (response)
+          LOG.info(
+            `Got response from ${subagent}`,
+            { messageId },
+            "\n\n" + truncated(response) + "\n",
+          )
+        return response
       } catch (err) {
-        LOG.warn("Sub-agent tool error", { agent: agentCard.name, error: err.message })
-        return `Error communicating with ${agentCard.name}: ${err.message}`
+        LOG.warn("Subagent tool error", { subagent, error: err.message })
+        return `Error communicating with ${subagent}: ${err.message}`
       }
     },
     {
@@ -100,13 +120,13 @@ function createA2ATool(client, agentCard) {
 
 export async function buildSubAgentToolLocally(serviceName) {
   const srv = cds.services[serviceName]
-  if (!srv) throw new Error(`[sub-agents] No local service "${serviceName}" found.`)
+  if (!srv) throw new Error(`[subagents] 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})`)
+  LOG.info(`Connecting to subagent ${serviceName}`, "(local)")
 
   const { RequestContext, DefaultExecutionEventBus } = await import("@a2a-js/sdk/server")
 
@@ -135,7 +155,7 @@ export async function buildSubAgentToolLocally(serviceName) {
             .map((p) => p.text)
             .join("\n")
           if (text) statusText = text
-          if (state === "failed") failed = text || "Sub-agent execution failed."
+          if (state === "failed") failed = text || "Subagent execution failed."
         } else if (event.kind === "artifact-update") {
           const parts = event.artifact?.parts || []
           if (event.artifact?.artifactId === "response") {
@@ -164,19 +184,17 @@ export async function buildSubAgentToolLocally(serviceName) {
         taskId,
         contextId,
       )
-      const truncated = message?.length > 80 ? message.slice(0, 80) + "..." : message
 
       try {
-        // Run the sub-agent detached from the calling agent, in its own root
+        // Run the subagent 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 () => {
-              LOG.info("request", {
+              LOG.info(srv.name, "-", "request", {
                 conversation: short(contextId),
-                service: srv.name,
-                text: truncated,
+                text: truncated(message),
               })
 
               await executor.execute(requestContext, eventBus)
@@ -186,7 +204,7 @@ export async function buildSubAgentToolLocally(serviceName) {
             .on("failed", reject)
         })
       } catch (err) {
-        LOG.warn("Local sub-agent tool error", { agent: agentCard.name, error: err.message })
+        LOG.warn("Local subagent tool error", { agent: agentCard.name, error: err.message })
         return `Error running ${agentCard.name}: ${err.message}`
       }
 
@@ -226,7 +244,7 @@ export async function buildSubAgentToolFromConnection(serviceName) {
 
   if (!localUrl && !destinationName) {
     throw new Error(
-      `[sub-agents] Could not resolve URL or destination name for service "${serviceName}". Check cds.requires config.`,
+      `[subagents] Could not resolve URL or destination name for service "${serviceName}". Check cds.requires config.`,
     )
   }
 
@@ -274,13 +292,13 @@ export async function buildSubAgentToolFromConnection(serviceName) {
 
   if (!agentBaseUrl) {
     throw new Error(
-      `[sub-agents] Could not resolve URL for service "${serviceName}" after destination lookup.`,
+      `[subagents] Could not resolve URL for service "${serviceName}" after destination lookup.`,
     )
   }
 
   const path = typeof credentials === "object" ? credentials?.path : null
   const base = agentBaseUrl.replace(/\/$/, "") + (path ? `/${path.replace(/^\//, "")}` : "")
-  LOG.info(`Connecting to sub-agent at ${base}`)
+  LOG.info(`Connecting to subagent ${serviceName}`, { at: base })
 
   // revisit: a2a agents may be tenant specific, card per tenant?
   const initialHeaders = await resolveHeaders()
@@ -290,17 +308,20 @@ export async function buildSubAgentToolFromConnection(serviceName) {
   })
   if (!cardRes.ok) {
     throw new Error(
-      `[sub-agents] Agent card fetch failed for "${serviceName}" at ${cardUrl}: HTTP ${cardRes.status}`,
+      `[subagents] 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()
+    if (getTracer()) {
+      const { context, propagation } = await import("@opentelemetry/api")
+      propagation.inject(context.active(), headers)
+    }
     return fetch(url, { ...init, headers: { ...headers, ...(init.headers || {}) } })
   }
   const factory = new ClientFactory(

package/srv/handlers/tools.js

@@ -11,7 +11,7 @@ import {
   executeCallActionTool,
   executePerActionTool,
 } from "@cap-js/mcp/lib/tools.js"
-import { getFilteredEntities, getFilteredActions, getAgentLogger } from "../../lib/utils/utils.js"
+import { getFilteredEntities, getFilteredActions } from "../../lib/utils/utils.js"
 import { isTextMime } from "../../lib/agents/markdown/backends/mime-utils.js"
 import { checkAuthorization } from "@cap-js/mcp/lib/auth.js"
 
@@ -31,7 +31,6 @@ function cachedAuth(srv) {
 
 class GenericReadTool extends DynamicStructuredTool {
   constructor(srv, entities) {
-    const log = getAgentLogger(srv)
     const def = createGenericReadToolDefinition(Object.keys(entities), srv.name, "")
     super({
       name: def.name,
@@ -39,7 +38,7 @@ class GenericReadTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeGenericReadTool(srv, entities, args, { log }))
+        return unwrap(await executeGenericReadTool(srv, entities, args))
       },
     })
     this.srv = srv
@@ -68,7 +67,6 @@ class GenericReadTool extends DynamicStructuredTool {
 
 class DescribeTool extends DynamicStructuredTool {
   constructor(srv, entities, actions) {
-    const log = getAgentLogger(srv)
     const def = createDescribeToolDefinition(
       Object.keys(entities),
       Object.keys(actions),
@@ -81,7 +79,7 @@ class DescribeTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeDescribe(srv, entities, actions, args, { log }))
+        return unwrap(await executeDescribe(srv, entities, actions, args))
       },
     })
     this.srv = srv
@@ -121,7 +119,6 @@ class DescribeTool extends DynamicStructuredTool {
 
 class PerActionTool extends DynamicStructuredTool {
   constructor(srv, actionName, action) {
-    const log = getAgentLogger(srv)
     const def = createPerActionToolDefinition(actionName, action, srv.name, srv.model, "")
     super({
       name: def.name,
@@ -129,7 +126,7 @@ class PerActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executePerActionTool(srv, actionName, action, args, { log }))
+        return unwrap(await executePerActionTool(srv, actionName, action, args))
       },
     })
     this.srv = srv
@@ -145,7 +142,6 @@ class PerActionTool extends DynamicStructuredTool {
 
 class CallActionTool extends DynamicStructuredTool {
   constructor(srv, actions) {
-    const log = getAgentLogger(srv)
     const def = createCallActionToolDefinition(Object.keys(actions), srv.name, "")
     super({
       name: def.name,
@@ -153,7 +149,7 @@ class CallActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeCallActionTool(srv, actions, args, { log }))
+        return unwrap(await executeCallActionTool(srv, actions, args))
       },
     })
     this.srv = srv
@@ -222,6 +218,10 @@ export function generateTools(srv) {
     tools.push(createEmitFilePartTool())
   }
 
+  if (cds.env.agents?.emitDataParts) {
+    tools.push(createEmitDataPartTool())
+  }
+
   return tools
 }
 
@@ -368,3 +368,29 @@ export function createReadFileTool(fileStore, contextId, userId) {
     },
   )
 }
+
+/**
+ * Create a tool that emits a DataPart in the A2A response.
+ * The executor's toolResults collection detects `kind: "data"`
+ * and emits the tool result as a data part.
+ */
+export function createEmitDataPartTool() {
+  return tool(
+    async ({ data, mediaType }) => {
+      return {
+        kind: "data",
+        data,
+        mediaType: mediaType ?? "application/json",
+      }
+    },
+    {
+      name: "emit_data_part",
+      description: "Emit a structured A2A DataPart. Only use when instructed.",
+      schema: z.object({
+        // A2A DataPart is specified to be an object in A2A 0.3
+        // https://a2a-protocol.org/v0.3.0/specification/#653-datapart-object
+        data: z.looseObject().describe("Structured object"),
+      }),
+    },
+  )
+}

package/lib/agents/middleware/hitl-edit-note-injector.js

@@ -1,18 +0,0 @@
-import { createMiddleware } from "langchain"
-import { HumanMessage } from "@langchain/core/messages"
-import { z } from "zod"
-
-// Injects a HumanMessage for a pending _hitlEditNote before the next model turn.
-export function hitlEditNoteInjectorMiddleware() {
-  return createMiddleware({
-    name: "hitlEditNoteInjectorMiddleware",
-    stateSchema: z.object({ _hitlEditNote: z.string().optional() }),
-    beforeModel: async (state) => {
-      if (!state._hitlEditNote) return
-      return {
-        messages: [new HumanMessage(state._hitlEditNote)],
-        _hitlEditNote: undefined,
-      }
-    },
-  })
-}