improvement(managed-agents): complete session inputs/outputs; trim block templates

- add memory instructions + file mount_path inputs; bound metadata (16 pairs)
- surface cumulative token usage (inputTokens/outputTokens) as outputs
- validate the full session-create schema against live docs
- remove BlockMeta templates

Author: waleedlatif1

apps/sim/app/api/tools/managed-agent/run/route.ts

@@ -94,7 +94,8 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     vaultIds: body.vaults,
     memoryStoreId: body.memoryStoreId,
     memoryAccess: body.memoryAccess,
-    fileIds: body.fileIds,
+    memoryInstructions: body.memoryInstructions,
+    files: body.files,
     sessionParameters: body.sessionParameters,
     signal: request.signal,
   })
@@ -114,6 +115,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
   return NextResponse.json({
     success: true,
-    output: { content: result.content, sessionId: result.sessionId ?? '' },
+    output: {
+      content: result.content,
+      sessionId: result.sessionId ?? '',
+      ...(result.inputTokens !== undefined ? { inputTokens: result.inputTokens } : {}),
+      ...(result.outputTokens !== undefined ? { outputTokens: result.outputTokens } : {}),
+    },
   })
 })

apps/sim/blocks/blocks/managed_agent.ts

@@ -103,14 +103,23 @@ export const ManagedAgentBlock: BlockConfig = {
       condition: { field: 'memoryStoreId', value: '', not: true },
       description: 'read_write pushes changes back on session exit; read_only never writes.',
     },
+    {
+      id: 'memoryInstructions',
+      title: 'Memory instructions',
+      type: 'long-input',
+      required: false,
+      placeholder: 'Optional — how the agent should use this memory store',
+      condition: { field: 'memoryStoreId', value: '', not: true },
+      description: 'Per-attachment guidance rendered into the memory section of the system prompt.',
+    },
     {
       id: 'files',
       title: 'Files',
       type: 'table',
       required: false,
-      columns: ['File ID'],
+      columns: ['File ID', 'Mount path'],
       description:
-        'Files-API file ids (file_...) to attach to the session as file resources (cloud environments).',
+        'Files-API file ids (file_...) to attach as file resources (cloud environments). Mount path is optional.',
     },
     {
       id: 'sessionParameters',
@@ -142,27 +151,22 @@ export const ManagedAgentBlock: BlockConfig = {
       type: 'string',
       description: "Memory store access mode — 'read_write' (default) or 'read_only'.",
     },
-    files: { type: 'json', description: 'Files-API file ids to attach as file resources.' },
+    memoryInstructions: {
+      type: 'string',
+      description: 'Per-attachment guidance for how the agent should use the memory store.',
+    },
+    files: { type: 'json', description: 'File attachments — [{fileId, mountPath?}].' },
     sessionParameters: { type: 'json', description: 'Session metadata (key/value).' },
   },
   outputs: {
     content: { type: 'string', description: "The Managed Agent's final assistant text." },
     sessionId: { type: 'string', description: 'Anthropic session id, for logs and linking.' },
+    inputTokens: { type: 'number', description: 'Cumulative input tokens for the session.' },
+    outputTokens: { type: 'number', description: 'Cumulative output tokens for the session.' },
   },
 }
 
 export const ManagedAgentBlockMeta = {
   tags: ['agentic', 'llm'],
   url: 'https://platform.claude.com/',
-  templates: [
-    {
-      icon: ClaudeIcon,
-      title: 'Delegate a task to a Claude Managed Agent',
-      prompt:
-        "Build a workflow that opens a Claude Platform Managed Agent session, optionally attaches a memory store and files, and captures the agent's response.",
-      modules: ['agent', 'workflows'],
-      category: 'engineering',
-      tags: ['automation', 'analysis'],
-    },
-  ],
 } as const satisfies BlockMeta

apps/sim/lib/api/contracts/managed-agents.ts

@@ -51,6 +51,25 @@ export type ListManagedAgentOptions = ContractJsonResponse<typeof listManagedAge
  * clean shapes in `request.body` before dispatch, so the route validates
  * strict types.
  */
+/** `metadata` is capped by the API at 16 pairs, keys ≤64, values ≤512 chars. */
+const sessionMetadataSchema = z.record(z.string(), z.string()).superRefine((value, ctx) => {
+  const entries = Object.entries(value)
+  if (entries.length > 16) {
+    ctx.addIssue({ code: 'custom', message: 'At most 16 metadata pairs are allowed.' })
+  }
+  for (const [key, val] of entries) {
+    if (key.length > 64) {
+      ctx.addIssue({ code: 'custom', message: `Metadata key "${key}" exceeds 64 characters.` })
+    }
+    if (val.length > 512) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `Metadata value for "${key}" exceeds 512 characters.`,
+      })
+    }
+  }
+})
+
 export const runManagedAgentBodySchema = z.object({
   agent: z.string().min(1, 'agent is required'),
   environment: z.string().min(1, 'environment is required'),
@@ -59,8 +78,12 @@ export const runManagedAgentBodySchema = z.object({
   vaultsAck: z.boolean().optional(),
   memoryStoreId: z.string().optional(),
   memoryAccess: z.enum(['read_write', 'read_only']).optional(),
-  fileIds: z.array(z.string().min(1)).max(100).optional(),
-  sessionParameters: z.record(z.string(), z.string()).optional(),
+  memoryInstructions: z.string().max(4096).optional(),
+  files: z
+    .array(z.object({ fileId: z.string().min(1), mountPath: z.string().min(1).optional() }))
+    .max(100)
+    .optional(),
+  sessionParameters: sessionMetadataSchema.optional(),
 })
 export type RunManagedAgentBody = z.input<typeof runManagedAgentBodySchema>
 
@@ -79,7 +102,12 @@ export const runManagedAgentContract = defineRouteContract({
     mode: 'json',
     schema: z.object({
       success: z.literal(true),
-      output: z.object({ content: z.string(), sessionId: z.string() }),
+      output: z.object({
+        content: z.string(),
+        sessionId: z.string(),
+        inputTokens: z.number().optional(),
+        outputTokens: z.number().optional(),
+      }),
     }),
   },
 })

apps/sim/lib/managed-agents/run-session.test.ts

@@ -11,6 +11,7 @@ const { mocks } = vi.hoisted(() => ({
     sendSessionEvents: vi.fn(),
     openSessionStream: vi.fn(),
     listSessionEvents: vi.fn(),
+    getSessionUsage: vi.fn(),
     readSSEEvents: vi.fn(),
     sleep: vi.fn(),
   },
@@ -22,6 +23,7 @@ vi.mock('@/lib/managed-agents/session-client', () => ({
   sendSessionEvents: mocks.sendSessionEvents,
   openSessionStream: mocks.openSessionStream,
   listSessionEvents: mocks.listSessionEvents,
+  getSessionUsage: mocks.getSessionUsage,
 }))
 vi.mock('@/lib/core/utils/sse', () => ({ readSSEEvents: mocks.readSSEEvents }))
 vi.mock('@sim/utils/helpers', () => ({ sleep: mocks.sleep }))
@@ -60,6 +62,7 @@ beforeEach(() => {
   mocks.createSession.mockResolvedValue({ id: 'sess_1' })
   mocks.sendUserMessage.mockResolvedValue(undefined)
   mocks.openSessionStream.mockResolvedValue({})
+  mocks.getSessionUsage.mockResolvedValue(null)
 })
 
 describe('runManagedAgentSession', () => {
@@ -78,6 +81,26 @@ describe('runManagedAgentSession', () => {
     expect(mocks.listSessionEvents).not.toHaveBeenCalled()
   })
 
+  it('surfaces cumulative token usage on success (best-effort)', async () => {
+    scriptStreamBatches([
+      [
+        msg('e1', 'ok'),
+        { id: 'e2', type: 'session.status_idle', stop_reason: { type: 'end_turn' } },
+      ],
+    ])
+    mocks.getSessionUsage.mockResolvedValue({ inputTokens: 120, outputTokens: 45 })
+
+    const result = await runManagedAgentSession({ ...BASE })
+
+    expect(result).toEqual({
+      ok: true,
+      content: 'ok',
+      sessionId: 'sess_1',
+      inputTokens: 120,
+      outputTokens: 45,
+    })
+  })
+
   it('does NOT false-timeout after requires_action followed by progress then a quiet reconnect', async () => {
     // Stream 1: only a requires_action idle (busy), then the stream closes.
     // Stream 2: closes immediately with nothing new.

apps/sim/lib/managed-agents/run-session.ts

@@ -6,6 +6,7 @@ import {
   type AnthropicSessionEvent,
   type CreateSessionInput,
   createSession,
+  getSessionUsage,
   listSessionEvents,
   openSessionStream,
   sendSessionEvents,
@@ -48,7 +49,8 @@ export interface RunManagedAgentInput {
   vaultIds?: string[]
   memoryStoreId?: string
   memoryAccess?: 'read_write' | 'read_only'
-  fileIds?: string[]
+  memoryInstructions?: string
+  files?: Array<{ fileId: string; mountPath?: string }>
   sessionParameters?: Record<string, string>
   signal?: AbortSignal
 }
@@ -58,6 +60,8 @@ export interface RunManagedAgentResult {
   content: string
   sessionId?: string
   error?: string
+  inputTokens?: number
+  outputTokens?: number
 }
 
 export async function runManagedAgentSession(
@@ -77,7 +81,10 @@ export async function runManagedAgentSession(
     ...(input.vaultIds && input.vaultIds.length > 0 ? { vaultIds: input.vaultIds } : {}),
     ...(input.memoryStoreId ? { memoryStoreId: input.memoryStoreId } : {}),
     ...(input.memoryStoreId && input.memoryAccess ? { memoryAccess: input.memoryAccess } : {}),
-    ...(input.fileIds && input.fileIds.length > 0 ? { fileIds: input.fileIds } : {}),
+    ...(input.memoryStoreId && input.memoryInstructions
+      ? { memoryInstructions: input.memoryInstructions }
+      : {}),
+    ...(input.files && input.files.length > 0 ? { files: input.files } : {}),
     ...(input.sessionParameters && Object.keys(input.sessionParameters).length > 0
       ? { sessionParameters: input.sessionParameters }
       : {}),
@@ -209,7 +216,17 @@ export async function runManagedAgentSession(
       error: terminal?.reason ?? 'Reconnect iteration cap reached without a terminal state.',
     }
   }
-  return { ok: true, content: assistantText.value, sessionId }
+
+  // Best-effort: surface cumulative token usage. A failed lookup never fails
+  // the run — the assistant text is already the result.
+  const usage = await getSessionUsage({ apiKey, sessionId, signal })
+  return {
+    ok: true,
+    content: assistantText.value,
+    sessionId,
+    ...(usage?.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+    ...(usage?.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+  }
 }
 
 /** Tracks progress across `requires_action` idle events. */

apps/sim/lib/managed-agents/session-client.test.ts

@@ -51,10 +51,29 @@ describe('buildSessionCreatePayload — resources', () => {
     ])
   })
 
-  it('attaches file resources by id (no mount path)', () => {
-    const payload = buildSessionCreatePayload({ ...BASE, fileIds: ['file_1', 'file_2'] })
+  it('includes memory instructions when provided', () => {
+    const payload = buildSessionCreatePayload({
+      ...BASE,
+      memoryStoreId: 'memstore_01',
+      memoryInstructions: 'check before starting',
+    })
     expect(payload.resources).toEqual([
-      { type: 'file', file_id: 'file_1' },
+      {
+        type: 'memory_store',
+        memory_store_id: 'memstore_01',
+        access: 'read_write',
+        instructions: 'check before starting',
+      },
+    ])
+  })
+
+  it('attaches file resources with an optional mount path', () => {
+    const payload = buildSessionCreatePayload({
+      ...BASE,
+      files: [{ fileId: 'file_1', mountPath: '/data/one' }, { fileId: 'file_2' }],
+    })
+    expect(payload.resources).toEqual([
+      { type: 'file', file_id: 'file_1', mount_path: '/data/one' },
       { type: 'file', file_id: 'file_2' },
     ])
   })
@@ -63,7 +82,7 @@ describe('buildSessionCreatePayload — resources', () => {
     const payload = buildSessionCreatePayload({
       ...BASE,
       memoryStoreId: 'memstore_01',
-      fileIds: ['file_1'],
+      files: [{ fileId: 'file_1' }],
     })
     expect(payload.resources).toEqual([
       { type: 'memory_store', memory_store_id: 'memstore_01', access: 'read_write' },
@@ -73,7 +92,7 @@ describe('buildSessionCreatePayload — resources', () => {
 
   it('omits `resources` when nothing is attached', () => {
     expect(buildSessionCreatePayload({ ...BASE }).resources).toBeUndefined()
-    expect(buildSessionCreatePayload({ ...BASE, fileIds: [] }).resources).toBeUndefined()
+    expect(buildSessionCreatePayload({ ...BASE, files: [] }).resources).toBeUndefined()
   })
 })
 

apps/sim/lib/managed-agents/session-client.ts

@@ -57,8 +57,10 @@ export interface CreateSessionInput extends SessionAuth {
   memoryStoreId?: string
   /** Access mode on the attached memory store. Ignored when `memoryStoreId` is unset. */
   memoryAccess?: 'read_write' | 'read_only'
-  /** Files-API file ids (`file_...`) attached as `file` session resources. */
-  fileIds?: string[]
+  /** Per-attachment guidance rendered into the memory section of the system prompt. */
+  memoryInstructions?: string
+  /** Files-API files (`file_...`) attached as `file` session resources. */
+  files?: Array<{ fileId: string; mountPath?: string }>
   /** Arbitrary session metadata (wire name: `metadata`). */
   sessionParameters?: Record<string, string>
 }
@@ -67,6 +69,12 @@ export interface CreateSessionResult {
   id: string
 }
 
+/** Cumulative token usage returned on the session resource. */
+export interface SessionUsage {
+  inputTokens?: number
+  outputTokens?: number
+}
+
 /**
  * Standard header set for Managed Agents calls. `beta` overrides the default
  * managed-agents beta for memory-store endpoints. Only ONE beta value is ever
@@ -102,15 +110,20 @@ export function buildSessionCreatePayload(input: CreateSessionInput): Record<str
 
   const resources: Array<Record<string, unknown>> = []
   if (input.memoryStoreId) {
-    resources.push({
+    const memory: Record<string, unknown> = {
       type: 'memory_store',
       memory_store_id: input.memoryStoreId,
       access: input.memoryAccess ?? 'read_write',
-    })
+    }
+    if (input.memoryInstructions) memory.instructions = input.memoryInstructions
+    resources.push(memory)
   }
-  if (input.fileIds && input.fileIds.length > 0) {
-    for (const fileId of input.fileIds) {
-      if (fileId) resources.push({ type: 'file', file_id: fileId })
+  if (input.files && input.files.length > 0) {
+    for (const file of input.files) {
+      if (!file.fileId) continue
+      const entry: Record<string, unknown> = { type: 'file', file_id: file.fileId }
+      if (file.mountPath) entry.mount_path = file.mountPath
+      resources.push(entry)
     }
   }
   if (resources.length > 0) payload.resources = resources
@@ -273,3 +286,30 @@ export async function managedAgentsList<T>(
     beta: input.beta,
   })
 }
+
+/**
+ * GET /v1/sessions/{id} — retrieves the session resource. Used after a run
+ * completes to surface cumulative token usage. Returns `null` on any error so
+ * the caller can treat usage as best-effort without failing the run.
+ */
+export async function getSessionUsage(
+  input: SessionAuth & { sessionId: string }
+): Promise<SessionUsage | null> {
+  try {
+    const resp = await fetch(`${ANTHROPIC_API_BASE}/v1/sessions/${input.sessionId}`, {
+      method: 'GET',
+      headers: managedAgentsHeaders(input.apiKey),
+      signal: input.signal,
+    })
+    if (!resp.ok) return null
+    const body = (await resp.json()) as {
+      usage?: { input_tokens?: unknown; output_tokens?: unknown }
+    }
+    const usage: SessionUsage = {}
+    if (typeof body.usage?.input_tokens === 'number') usage.inputTokens = body.usage.input_tokens
+    if (typeof body.usage?.output_tokens === 'number') usage.outputTokens = body.usage.output_tokens
+    return usage
+  } catch {
+    return null
+  }
+}