{"record":{"id":"899455dbf786e64d","repo":"mastra-ai/mastra","slug":"list-available-agents-requires-a-mastra-context","errorCode":null,"errorMessage":"list-available-agents requires a Mastra context.","messagePattern":"list-available-agents requires a Mastra context\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/tools/workflows/list-available-agents.ts","lineNumber":29,"sourceCode":"export const listAvailableAgentsTool = createTool({\n  id: 'list-available-agents',\n  description:\n    'Returns the agents currently registered on the Mastra instance. The agent ids returned here are the only valid values you can put in `{ type: \"agent\", agentId }` graph entries. `outputShape` describes the default text output; an entry-level `outputSchema` replaces that default with structured output.',\n  inputSchema: z.object({}),\n  outputSchema: z.object({\n    agents: z.array(\n      z.object({\n        id: z.string(),\n        description: z.string().optional(),\n        // Human-readable string in v1. Could become a JSON Schema now that\n        // structuredOutput round-trips through the rehydrator\n        // (packages/core/src/workflows/rehydrate-workflow.ts).\n        outputShape: z.string(),\n      }),\n    ),\n  }),\n  execute: async (_input, { mastra }) => {\n    if (!mastra) throw new Error('list-available-agents requires a Mastra context.');\n    const all = (mastra as { listAgents?: () => Record<string, unknown> }).listAgents?.() ?? {};\n    return {\n      agents: Object.entries(all)\n        .filter(([id]) => !WORKFLOW_BUILDER_NOISE_AGENTS.has(id))\n        .map(([id, a]) => ({\n          id,\n          description: (a as { description?: string } | undefined)?.description,\n          outputShape: 'Default: { text: string }. An entry-level outputSchema produces that schema instead.',\n        })),\n    };\n  },\n});\n","sourceCodeStart":11,"sourceCodeEnd":42,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/tools/workflows/list-available-agents.ts#L11-L42","documentation":"list-available-agents is a Mastra tool whose execute destructures the runtime context and requires a `mastra` instance to enumerate registered agents. The library throws this Error when the tool is executed without a Mastra context, which happens when the tool runs outside a Mastra server/agent runtime (e.g. invoked directly, or registered on a non-Mastra execution harness). It is a fail-fast guard because without the instance there is no registry to read agents from.","triggerScenarios":"Executing the list-available-agents tool with a runtime context whose `mastra` property is undefined — e.g. calling `tool.execute()` manually without a Mastra-bound context, registering the tool in a harness that does not inject Mastra, or running it in tests with a stubbed executionContext.","commonSituations":"Unit tests invoking the tool with a fake context object missing `mastra`; embedding the SDK tool in a custom runner/framework (not Mastra Studio or a Mastra agent) that omits context injection; calling execute before server/agent initialization completes.","solutions":["Run the tool through a Mastra runtime (Mastra agent, server, or Studio) so the context carries the `mastra` instance.","In custom code, pass an executionContext that includes `mastra: new Mastra({ agents: ... })` when calling tool.execute.","If testing, construct the context with a real or minimal Mastra instance instead of omitting it.","Verify you are not calling the tool's execute directly before Mastra initialization (e.g. before `await mastra.startServers()` or agent construction)."],"exampleFix":"// before\nawait tool.execute({ workflowId: 'x' }, {} as any); // no mastra\n// after\nimport { Mastra } from '@mastra/core';\nconst mastra = new Mastra({ agents: { myAgent } });\nawait tool.execute({ workflowId: 'x' }, { mastra, requestContext: new RequestContext() });","handlingStrategy":"try-catch","validationCode":"// before invoking the tool\nif (!ctx || typeof ctx !== 'object' || !('mastra' in ctx) || !ctx.mastra) {\n  throw new Error('list-available-agents must run inside a Mastra runtime context.');\n}","typeGuard":"function hasMastraContext(ctx: unknown): ctx is { mastra: NonNullable<unknown>; requestContext?: unknown } {\n  return (\n    typeof ctx === 'object' &&\n    ctx !== null &&\n    'mastra' in ctx &&\n    (ctx as { mastra?: unknown }).mastra != null\n  );\n}","tryCatchPattern":"try {\n  const res = await tool.execute(input, ctx);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('requires a Mastra context')) {\n    // re-run inside a Mastra runtime or inject `mastra` into the context\n  } else {\n    throw err;\n  }\n}","preventionTips":["Always execute SDK tools through a Mastra agent, server, or Studio rather than calling execute directly.","When calling execute manually, always include a constructed Mastra instance in the executionContext.","In tests, build a shared helper that creates a context object containing `mastra`.","Assert on context shape (hasMastraContext) before invoking tools in custom runners.","Keep tool registration tied to the Mastra instance so context injection is automatic."],"tags":["mastra","configuration","runtime-context","tools"],"backgroundTag":"missing-mastra-context","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}