mastra-ai/mastra · error · HTTPException

Responses requests require an agent_id

Error message

Responses requests require an agent_id

What it means

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.

Source

Thrown at packages/server/src/server/handlers/responses.ts:301

    memory: {
      thread: threadContext.threadId,
      resource: threadContext.resourceId,
    },
  } as const;
}

/**
 * Resolves the registered Mastra agent that owns the response request.
 */
async function resolveResponseAgent({
  mastra,
  agentId,
}: {
  mastra: Mastra | undefined;
  agentId?: string;
}): Promise<Agent<any, any, any, any>> {
  if (!agentId) {
    throw new HTTPException(400, {
      message: 'Responses requests require an agent_id',
    });
  }

  if (!mastra) {
    throw new HTTPException(500, { message: 'Mastra instance is required for agent-backed responses' });
  }

  return getAgentFromSystem({ mastra, agentId });
}

async function resolveAgentMemoryStore({
  agent,
  requestContext,
  errorMessage,
}: {
  agent: Agent<any, any, any, any>;
  requestContext: RequestContext;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add agent_id to the request body with the registered agent's name/id
2. Verify the payload is actually JSON with the field present (log the outgoing body)
3. Check client SDK usage — pass the agent id in the documented field
4. If routing to a non-agent responder, use the appropriate endpoint rather than /api/responses

Example fix

// before
fetch('/api/responses', { method: 'POST', body: JSON.stringify({ input: 'hi' }) });
// after
fetch('/api/responses', { method: 'POST', body: JSON.stringify({ agent_id: 'weatherAgent', input: 'hi' }) });

if (!body.agent_id) throw new Error('agent_id is required for /api/responses');

function hasAgentId(body) { return typeof body?.agent_id === 'string' && body.agent_id.length > 0; }

null

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• conversation_id and previous_response_id must reference the
• Cannot delete the active version. Activate a different versi
• ${error.message}
• conversation_id requires the target agent to have memory con
• ${errorMessage}

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/d3905618041763d9. Report an issue: GitHub.