import Steps from "@site/src/components/Steps"; import StepItem from "@site/src/components/StepItem"; import YouTube from "@site/src/components/YouTube-player";

Building an AI stock agent

In this guide, you're going to create an agent that fetches the last day's closing stock price for a given symbol. You'll learn how to create a tool, add it to an agent, and use the agent to fetch stock prices.

Prerequisites

Node.js v22.13.0 or later installed
An API key from a supported Model Provider
An existing Mastra project (Follow the installation guide to set up a new project)

Creating the agent

To create an agent in Mastra use the Agent class to define it and then register it with Mastra.

<Steps> <StepItem> Create a new file `src/mastra/agents/stockAgent.ts` and define your agent:

```ts title="src/mastra/agents/stockAgent.ts"
import { Agent } from '@mastra/core/agent'

export const stockAgent = new Agent({
  id: 'stock-agent',
  name: 'Stock Agent',
  instructions:
    'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.',
  model: 'openai/gpt-5.4',
})
```

</StepItem> <StepItem> In your `src/mastra/index.ts` file, register the agent:

```ts title="src/mastra/index.ts" {2, 5}
import { Mastra } from '@mastra/core'
import { stockAgent } from './agents/stockAgent'

export const mastra = new Mastra({
  agents: { stockAgent },
})
```

</StepItem> </Steps>

Creating the stock price tool

The Stock Agent doesn't yet know anything about current stock prices. To change this, create a tool and add it to the agent.

<Steps> <StepItem> Create a new file `src/mastra/tools/stockPrices.ts`. Inside, add a `stockPrices` tool that will fetch the last day's closing stock price for a given symbol:

```ts title="src/mastra/tools/stockPrices.ts"
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const getStockPrice = async (symbol: string) => {
  const data = await fetch(
    `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`,
  ).then(r => r.json())
  return data.prices['4. close']
}

export const stockPrices = createTool({
  id: 'Get Stock Price',
  inputSchema: z.object({
    symbol: z.string(),
  }),
  description: `Fetches the last day's closing stock price for a given symbol`,
  execute: async inputData => {
    console.log('Using tool to fetch stock price for', inputData.symbol)
    return {
      symbol: inputData.symbol,
      currentPrice: await getStockPrice(inputData.symbol),
    }
  },
})
```

</StepItem> <StepItem> Inside `src/mastra/agents/stockAgent.ts` import your newly created `stockPrices` tool and add it to the agent.

```ts title="src/mastra/agents/stockAgent.ts" {9-11}
import { Agent } from '@mastra/core/agent'
import { stockPrices } from '../tools/stockPrices'

export const stockAgent = new Agent({
  id: 'stock-agent',
  name: 'Stock Agent',
  instructions:
    'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.',
  model: 'openai/gpt-5.4',
  tools: {
    stockPrices,
  },
})
```

</StepItem> </Steps>

Running the agent server

Learn how to interact with your agent through Mastra's API.

<Steps> <StepItem> You can run your agent as a service using the `mastra dev` command:

```bash
mastra dev
```

This will start a server exposing endpoints to interact with your registered agents. Within [Studio](/docs/getting-started/studio) you can test your `stockAgent` and `stockPrices` tool through a UI.

</StepItem> <StepItem> By default, `mastra dev` runs on `http://localhost:4111`. Your Stock agent will be available at:

```
POST http://localhost:4111/api/agents/stockAgent/generate
```

</StepItem> <StepItem> You can interact with the agent using `curl` from the command line:

```bash
curl -X POST http://localhost:4111/api/agents/stockAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What is the current stock price of Apple (AAPL)?" }
    ]
  }'
```

You should receive a JSON response similar to:

```json
{
  "text": "The current price of Apple (AAPL) is $174.55.",
  "agent": "Stock Agent"
}
```

This indicates that your agent successfully processed the request, used the `stockPrices` tool to fetch the stock price, and returned the result.

</StepItem> </Steps>

Guide: Building an AI stock agent

Building an AI stock agent

Prerequisites

Creating the agent

Creating the stock price tool

Running the agent server