Step-by-step, code-heavy guides for building AI agents.
84 posts
Measured on @voltagent/core 2.11.0: the first agent call lazily starts three setInterval timers that are never unref'd, so your Node process stays alive forever. Two of them poll 20 times a second. Here is the reproduction, the cause and the fix.
Measured on ai 7.0.118 and zod 4.6.5: a .refine() on a tool input schema is stripped before the schema reaches the model, with no warning. z.string().startsWith('acct_') arrives as a pattern; the same rule written as a refinement arrives as nothing.
On ai 7.0.116, generateText and streamText run exactly one step by default. Pass tools without stopWhen and the model calls a tool, your tool runs, and you get an empty string with no error. The same package defaults ToolLoopAgent to twenty. Measured on the wire, with the bundle lines that cause it.
On ai 7.0.114, whatever your tool execute function throws is serialised and sent to the model provider in a tool_result block marked is_error. The documented toModelOutput hook is skipped on that path. Measured first-party with a local capture server, no API key.
The Anthropic provider decides your max_tokens, whether temperature is sent at all, and the whole shape of a generateObject request, from a case-sensitive substring test on your model id. Reproduced first-party on ai 7.0.113 with a local capture server and no real API key.
An MCP stdio server that holds a timer or a pool open does not exit when its client dies. Measured on SDK 1.30.0 and Node 24.8.0: it is reparented to init and keeps running. StdioServerTransport registers no stdin end-of-file listener. Here is the reproduction and the four-line fix.
You gave your agent a shell tool, used execFile so there is no shell, and allowlisted the programs. It is still not safe. If the agent controls the argument array, tar's own --checkpoint-action=exec runs any command with no metacharacters. Here is the reproduction and the per-binary argument policy that stops it, measured on Node 24.8.0.
If your agent has a read_file tool, you probably guard it with path.resolve plus startsWith. It blocks the obvious traversal and is defeated by a symlink and by a sibling directory sharing the prefix. Both reproduced on Node 24.8.0, with the guard that passes all nine cases.
Agent frameworks build the request for you, then show you a summary of it. Here is a 60-line local server that records the exact JSON body your SDK sends, with no API key, no proxy and no certificate, plus the CI assertion a proxy cannot give you.
Mastra documents that the object key, not the tool id, becomes the name the model sees. It does not document that the key is rewritten first: invalid characters become underscores and the result is cut to 63. The tools array goes through that rewrite. toolChoice does not.
The SDK chooses reasoning.effort and text.verbosity from how your model name is spelled, not from what the model supports. Measured on the wire on 0.18.0, including what it does to a custom gateway deployment name.
allowedTools auto-approves, tools restricts. That half is documented. What is not: an AgentDefinition has no allowedTools field, and the SDK forwards one verbatim to the CLI anyway, unvalidated.
