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
- Tool configuration Agent ID, output schema, source allowlist and effort, set once in code. The model never sees them.
- A task per run One product and its suppliers, materials and freight lanes, from a three-product watchlist.
- 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
How it works
Six patterns for using @nimble-way/mastra, each one in its own file in the repo.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- @nimble-way/mastra Three non-blocking tools: start a run, check it, fetch the result.
- 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
- @mastra/core Workflows, agents, memory, server and Studio.
- claude-sonnet-4-6 Triage and the investigator chat.
- LibSQL Keeps runIds between ticks and the events already reported.
- GitHub Actions Triggers the workflows on a cron.
- TypeScript, Node.js 22.13+ Required by @nimble-way/mastra.

Reach out if you have any questions.
Talk to an Expert