{"record":{"id":"d3905618041763d9","repo":"mastra-ai/mastra","slug":"responses-requests-require-an-agent-id","errorCode":null,"errorMessage":"Responses requests require an agent_id","messagePattern":"Responses requests require an agent_id","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/responses.ts","lineNumber":301,"sourceCode":"    memory: {\n      thread: threadContext.threadId,\n      resource: threadContext.resourceId,\n    },\n  } as const;\n}\n\n/**\n * Resolves the registered Mastra agent that owns the response request.\n */\nasync function resolveResponseAgent({\n  mastra,\n  agentId,\n}: {\n  mastra: Mastra | undefined;\n  agentId?: string;\n}): Promise<Agent<any, any, any, any>> {\n  if (!agentId) {\n    throw new HTTPException(400, {\n      message: 'Responses requests require an agent_id',\n    });\n  }\n\n  if (!mastra) {\n    throw new HTTPException(500, { message: 'Mastra instance is required for agent-backed responses' });\n  }\n\n  return getAgentFromSystem({ mastra, agentId });\n}\n\nasync function resolveAgentMemoryStore({\n  agent,\n  requestContext,\n  errorMessage,\n}: {\n  agent: Agent<any, any, any, any>;\n  requestContext: RequestContext;","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/responses.ts#L283-L319","documentation":"The Responses endpoint is agent-backed: it must resolve a concrete Agent to execute. resolveResponseAgent throws this 400 when body.agent_id is missing/empty, before any agent lookup happens.","triggerScenarios":"POST /api/responses without agent_id in the JSON body, with agent_id: undefined/null/empty string, or a client that dropped the field during serialization.","commonSituations":"Hand-rolled curl/fetch payloads omitting agent_id; SDK version mismatch where the field was named differently (e.g., just 'agent' or 'model'); template code where the agent id variable was undefined at build time.","solutions":["Add agent_id to the request body with the registered agent's name/id","Verify the payload is actually JSON with the field present (log the outgoing body)","Check client SDK usage — pass the agent id in the documented field","If routing to a non-agent responder, use the appropriate endpoint rather than /api/responses"],"exampleFix":"// before\nfetch('/api/responses', { method: 'POST', body: JSON.stringify({ input: 'hi' }) });\n// after\nfetch('/api/responses', { method: 'POST', body: JSON.stringify({ agent_id: 'weatherAgent', input: 'hi' }) });","handlingStrategy":"validation","validationCode":"if (!body.agent_id) throw new Error('agent_id is required for /api/responses');","typeGuard":"function hasAgentId(body) { return typeof body?.agent_id === 'string' && body.agent_id.length > 0; }","tryCatchPattern":"null","preventionTips":["Validate request bodies against the schema before sending","Centralize response payload construction in one typed client helper","Log outgoing payloads when debugging 400s"],"tags":["server","validation","http-400","responses-api"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}