Mastra•3mo ago

Accessing messages inside a tool callback

Hey everyone,

I’m new to Mastra and have a quick question.

From what I understand, Mastra automatically passes messages to the agent (like in the config below). What I’m trying to figure out is: can I access those messages from within a tool callback?

Here’s a simplified example:

const agent = new Agent({
  ...

  tools: async ({ runtimeContext, mastra }) => {
    // How can I read the messages here that were passed to createCompletion?
    return {};
  },

  memory: new Memory({
    storage: new PostgresStore({
      connectionString: process.env.DATABASE_URL,
    }),
    vector: new PgVector({
      connectionString: process.env.DATABASE_URL,
    }),
    embedder: openai.embedding("text-embedding-3-small"),
    options: {
      lastMessages: 2,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
        scope: "thread",
        indexConfig: {
          type: "hnsw",
          metric: "dotproduct",
          m: 16,
          efConstruction: 64,
        },
      },
      threads: {
        generateTitle: true,
      },
    },
  }),
});

const agent = new Agent({
  ...

  tools: async ({ runtimeContext, mastra }) => {
    // How can I read the messages here that were passed to createCompletion?
    return {};
  },

  memory: new Memory({
    storage: new PostgresStore({
      connectionString: process.env.DATABASE_URL,
    }),
    vector: new PgVector({
      connectionString: process.env.DATABASE_URL,
    }),
    embedder: openai.embedding("text-embedding-3-small"),
    options: {
      lastMessages: 2,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
        scope: "thread",
        indexConfig: {
          type: "hnsw",
          metric: "dotproduct",
          m: 16,
          efConstruction: 64,
        },
      },
      threads: {
        generateTitle: true,
      },
    },
  }),
});

const agent = new Agent({
  ...

  tools: async ({ runtimeContext, mastra }) => {
    // How can I read the messages here that were passed to createCompletion?
    return {};
  },

  memory: new Memory({
    storage: new PostgresStore({
      connectionString: process.env.DATABASE_URL,
    }),
    vector: new PgVector({
      connectionString: process.env.DATABASE_URL,
    }),
    embedder: openai.embedding("text-embedding-3-small"),
    options: {
      lastMessages: 2,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
        scope: "thread",
        indexConfig: {
          type: "hnsw",
          metric: "dotproduct",
          m: 16,
          efConstruction: 64,
        },
      },
      threads: {
        generateTitle: true,
      },
    },
  }),
});

const agent = new Agent({
  ...

  tools: async ({ runtimeContext, mastra }) => {
    // How can I read the messages here that were passed to createCompletion?
    return {};
  },

  memory: new Memory({
    storage: new PostgresStore({
      connectionString: process.env.DATABASE_URL,
    }),
    vector: new PgVector({
      connectionString: process.env.DATABASE_URL,
    }),
    embedder: openai.embedding("text-embedding-3-small"),
    options: {
      lastMessages: 2,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
        scope: "thread",
        indexConfig: {
          type: "hnsw",
          metric: "dotproduct",
          m: 16,
          efConstruction: 64,
        },
      },
      threads: {
        generateTitle: true,
      },
    },
  }),
});

Any hints on how to tap into the messages inside the tool context would be appreciated!

_roamin_•10/15/25, 8:26 PM

Hi @Adnan A. ! You can actually access the messages in the second param of the execute handler, like this:

tools: async ({ runtimeContext, mastra }, options) => {
    // messages are in the options params   
    options?.messages

    return {};
  },

tools: async ({ runtimeContext, mastra }, options) => {
    // messages are in the options params   
    options?.messages

    return {};
  },

Adnan A.OP•10/16/25, 8:33 AM

Hi @Romain! thanks for getting back to me.
I tried what you suggested like this:

tools: async ({ runtimeContext, mastra }, options) => {
  console.log('options', options?.messages);
  return {};
},

tools: async ({ runtimeContext, mastra }, options) => {
  console.log('options', options?.messages);
  return {};
},

But in the console, options?.messages is undefined - actually, options itself is completely undefined.

Then I tried:

tools: async (...args) => {
  console.log('args', args);
  return {};
},

tools: async (...args) => {
  console.log('args', args);
  return {};
},

And I got this output:

args [
  {
    runtimeContext: RuntimeContext { registry: Map(0) {} },
    mastra: Mastra {}
  }
]

args [
  {
    runtimeContext: RuntimeContext { registry: Map(0) {} },
    mastra: Mastra {}
  }
]

Any idea how I can access the messages from here?

Adnan A.OP•10/16/25, 12:45 PM

I think there’s a bit of a misunderstanding - you’re referring to executing from tool/createTooltool/createTool, but I’m talking about the toolstools property inside an AgentAgent instance definition.

const agent = new Agent({
  tools: async ({ runtimeContext, mastra }) => {
    // i mean here..
    return {};
  },
}

const agent = new Agent({
  tools: async ({ runtimeContext, mastra }) => {
    // i mean here..
    return {};
  },
}

Guria•10/16/25, 12:54 PM

place you are asking is evaluated at agent creation time, there is no messages on that step yet

Guria•10/16/25, 12:56 PM

am I understand correctly that you want to dynamically override tools available based on messages passed to the agent?

Adnan A.OP•10/16/25, 6:39 PM

Hi @Guria!
That’s correct - I need access to both the messages coming from the request body and the ones retrieved by the memory instance (semantic matches).

This would help me implement dynamic tool selection, since I have a large set of tools and passing them all normally costs a lot of input tokens.

Do you have any suggestions or possible solutions for this?

Guria•10/16/25, 7:17 PM

try to check model middleware. it allows you manipulate context on low level before sending params to actual model instance. but be careful

Guria•10/16/25, 7:17 PM

https://ai-sdk.dev/docs/ai-sdk-core/middleware

Language Model Middleware

Learn how to use middleware to enhance the behavior of language models

__roamin_Hi @Adnan A. ! You can actually access the messages in the second param of the e...

Matt Buck•11/21/25, 3:03 PM

Thanks for this, Romain! I needed to access the current messages being generated as part of an assistant's turn in my tool (e.g. before they had been persisted). The optionsoptions argument does indeed work as part of the execute handler for a tool:

execute: async ({ context, runtimeContext }, options) => {
  options?.messages

execute: async ({ context, runtimeContext }, options) => {
  options?.messages

However, I couldn't find documentation for this optionsoptions argument:

https://mastra.ai/reference/tools/create-tool
https://mastra.ai/docs/agents/using-tools

The kapa.ai agent on the docs site also couldn't find a reference to this.

Reference: createTool() | Tools & MCP | Mastra Docs

Documentation for the createTool()createTool() function in Mastra, used to define custom tools for agents.

Using Tools | Agents | Mastra Docs

Learn how to create tools and add them to agents to extend capabilities beyond text generation.

Matt Buck•11/21/25, 3:13 PM

Actually, to amend my previous statement, this options.messagesoptions.messages array doesn't include the current assistant message being constructed.

For my use case, I'm attempting to do something like "send me the latest sales report in Slack":

the agent calls a generateSalesReportgenerateSalesReport tool
the agent then calls a sendToSlacksendToSlack tool

That sendToSlacksendToSlack tool needs to be able to access the results of the prior tool call (the sales report), but since that's part of the assistant message that's currently being constructed, it's not available via storage or the options.messagesoptions.messages array.

If I send two separate messages "generate the sales report" and then "send it to Slack" the tool can access the prior tool call results either from storage or the options.messagesoptions.messages array.

Is anyone aware of a method for accessing either the assistant message currently under construction, or prior tool calls?

Matt Buck•11/21/25, 3:38 PM

It just struck me that I can persist the tool call outputs to runtimeContextruntimeContext, but in some cases I'll also be interested in the text message outputs that have been generated by the assistant as part of its current turn.

Matt Buck•12/5/25, 6:28 PM

As a follow-up, my workaround here was to create another tool the agent can call if it wants to generate a text-only message that needs to be delivered to Slack. That way, the assistant message becomes a tool call I can persist to the runtimeContextruntimeContext.

Abhi Aiyer•12/5/25, 7:01 PM

Ah @Matt Buck this is a legit use case

Abhi Aiyer•12/5/25, 7:02 PM

We need to audit those messages being sent in tool calls

Scald•12/10/25, 8:27 AM

having the exact same use of trying to get the messages + the current agent generation inside of a tool call.

Abhi Aiyer•12/19/25, 9:45 PM

Interesting that this discussion didnt turn into a GH issue @_roamin_ ?

Accessing messages inside a tool callback

Similar Threads

Similar Threads

Similar Threads