Nimble Data Apps
Dev Tools

Live web research for Mastra agents

The @nimble-way/mastra package adds three typed tools to Mastra: start a Web Search Agent run, check it, and fetch the result. This cookbook uses them two ways: from a scheduled workflow, where code decides when a billed run starts, and from a chat agent that starts a deep dive in one turn and collects it in a later one. The example app is a supply chain monitor that reads per-claim citations out of every result.

Quick Start

Inputs

  1. Tool configuration Agent ID, output schema, source allowlist and effort, set once in code. The model never sees them.
  2. A task per run One product and its suppliers, materials and freight lanes, from a three-product watchlist.
  3. A trigger A cron call to the workflows, or a chat message to the agent in Mastra Studio.

Outputs

  • A runId within a second, the only handle needed to collect the run later
  • A schema-shaped answer, with sources and citations for each field
  • A confidence grade per field, used to decide what triggers an alert
  • Slack alerts and a daily digest of new and changed events
  • Cited deep-dive briefings on request, in Mastra Studio

The repo ships one recorded sweep per product plus the triage output, so the full sweep, collect and digest flow runs in demo mode with no billable calls.

View example on GitHub

How it works

Six patterns for using @nimble-way/mastra, each one in its own file in the repo.

  1. Configure the tools once createNimbleAgentTools(), or the single-tool factories, take the agent ID, outputSchema, sources and effort. The model only ever supplies the task.
  2. Start runs from a workflow step The sweep workflow calls the start-run tool directly, once per product, and stores each runId. No model decides whether to start a billed run.
  3. Collect on a later tick A separate collect workflow calls the result tool and branches on ready, never on status. Runs still working wait for the next tick, so the server can sleep in between.
  4. Read evidence per field With an outputSchema, claims come back keyed by JSON path, so each event in the answer carries its own citations and confidence grade.
  5. Give the same tools to an agent The investigator agent gets createNimbleAgentTools() with an effortCap, starts a deep dive in one turn, and collects the cited briefing in a later one.
  6. Start once, never retry Run creation is sent once. The workflow records a failed start's createOutcome and the agent's instructions forbid a second run, so a timeout never turns into a second billed run.

Stack

Nimble primitives plus the full runtime stack.
Nimble APIs
What it does
  1. @nimble-way/mastra Three non-blocking tools: start a run, check it, fetch the result.
  2. Web Search Agents Two agents: one checks trade press and official notices for new events on every sweep, the other researches a single event in depth on request.
3rd Party Tools
Role
  1. @mastra/core Workflows, agents, memory, server and Studio.
  2. claude-sonnet-4-6 Triage and the investigator chat.
  3. LibSQL Keeps runIds between ticks and the events already reported.
  4. GitHub Actions Triggers the workflows on a cron.
  5. TypeScript, Node.js 22.13+ Required by @nimble-way/mastra.
Reach out if you have any questions.
Talk to an Expert