docs(agent-sdk): add tool-call example backed by a NATS microservice

[M64GitHub]

What

Adds agent-sdk/typescript/examples/03-tools.ts — step 3 of the agent-sdk example ladder (01-echo → 02-ollama → 03-tools).

The agent gains a read_sensor tool, and that tool is wired to a NATS microservice. The point of the example:

any microservice already on your NATS network can become an agent capability — without the agent embedding the device, database, or credential behind it.

The agent process holds only an LLM + a NATS connection. When the model needs live data it calls the tool; the tool's entire handler is one nc.request(...) to the microservice. For a self-contained single-file demo, the microservice (a faked temperature sensor) is registered in the same file — in production it runs anywhere on the network and the agent never knows where.

// the tool handler — this one line is the whole lesson:
const reply = await nc.request(SENSOR_SUBJECT, location, { timeout: 5000 });

How it works

Ollama /api/chat tool-calling in the canonical two round-trips:

1. Round 1 (non-streamed) — send the prompt + tool schema; the model asks to call read_sensor(location).
2. Run the tool (the NATS request), feed the result back.
3. Round 2 (streamed) — the model streams its final answer, reusing the exact token-streaming shape from 02-ollama.ts.

Default model llama3.1:8b (tool-capable), overridable via OLLAMA_MODEL; host via OLLAMA_URL.

Verification

Full end-to-end run against a local nats-server + Ollama:

• nats micro ls shows both services on the bus — agents (the agent) and sensors (the microservice it calls).
• A real prompt drove the complete path: ack → tool decision → NATS request to the sensor → streamed verdict ("No, the cold storage room 3 is not within the safe range…").
• typecheck, lint, format:check all clean; both SDKs build.

README updated with the new row and a run section (including a nats micro ls tip).

Context

Conference-talk material (reThinkConn) demonstrating the Synadia Agent Protocol in three small steps. This is the final step — giving an agent access to existing NATS microservices as tools.

🤖 Generated with Claude Code

[synadia-claude-reviewer]

Claude finished @M64GitHub's task in 2m 44s —— View job

---

PR Review: docs(agent-sdk): add tool-call example backed by a NATS microservice

• Gather context
• Read the diff and new files
• Review for correctness, security, and protocol compliance
• Post inline findings

---

The example is well-structured and clearly demonstrates the intended concept. Three issues worth addressing before merge, all in 03-tools.ts:

Severity	File	Issue
Medium	line 142	JSON.parse in chatStream without a try/catch — malformed Ollama output throws SyntaxError through the generator, resulting in a 500 error frame to the caller instead of a graceful partial response
Low	line 107	arguments typed as Record<string, unknown> but some Ollama versions (and several quantised llama variants) return it as a JSON-encoded string — runTool silently falls back to location = "" producing "no sensor at ''" with no diagnostic
Low	line 180	Tool response message lacks name: call.function.name — Ollama uses this field (not a tool_call_id) to attribute results; a second tool added later would produce ambiguous attribution

No protocol-compliance or security issues found. The NATS subject layout is correct (agents.prompt.tools.<owner>.<name>), the SDK's onPrompt / response.send pattern is used correctly, the sensor subject lookup is safe against injection (dict key lookup with an "unknown" fallback), and the two-round-trip tool-calling flow is a correct implementation of the Ollama /api/chat tool API.

The README additions are accurate and the nats micro ls tip is a useful touch for conference-demo use.

[synadia-claude-reviewer]

JSON.parse without error handling. If Ollama sends a non-JSON line (e.g., an error message during model loading or a truncated stream), this throws SyntaxError, propagates out of the generator, and causes the AgentService to emit a 500 error frame to the caller rather than a graceful partial response. 02-ollama.ts has the same gap, but it's worth fixing here as an incremental improvement:

Suggested change

	const token = (JSON.parse(line) as { message?: { content?: string } }).message?.content ?? "";
	try {
	const token = (JSON.parse(line) as { message?: { content?: string } }).message?.content ?? "";
	if (token) yield token;
	} catch {
	// ignore non-JSON lines (Ollama sometimes emits plain-text errors)
	}

[M64GitHub]

Fixed in dac36d9 — wrapped the streaming JSON.parse in try/catch so a rare non-JSON line is skipped instead of throwing out of the generator (which would surface as a 500 frame to the caller).

[synadia-claude-reviewer]

arguments may arrive as a JSON string for some models. The Ollama /api/chat response is typed here as Record<string, unknown>, which is correct for llama3.1:8b. However, some Ollama versions and several other models (including some quantised llama variants) return arguments as a JSON-encoded string rather than a parsed object. runTool checks typeof args["location"] === "string" which silently falls back to location = "" in that case, producing a confusing "no sensor at ''" from the model. A defensive parse guard at the call site would prevent the silent misbehaviour:

Suggested change

	tool_calls?: { function: { name: string; arguments: Record<string, unknown> } }[];
	tool_calls?: { function: { name: string; arguments: Record<string, unknown> | string } }[];

And then in runTool:

const rawArgs = typeof args === "string" ? (JSON.parse(args) as Record<string, unknown>) : args;
const location = typeof rawArgs["location"] === "string" ? rawArgs["location"] : "";

[M64GitHub]

Fixed in dac36d9 — runTool now accepts arguments as a parsed object or a JSON string (typeof args === "string" ? JSON.parse(args) : args), with the tool_calls type widened to Record<string, unknown> | string. Good call; this makes the example work across more models, which matters since it's meant to be run with OLLAMA_MODEL overrides. Verified end-to-end against a live Ollama afterward.

[synadia-claude-reviewer]

Missing name in tool response message. The Ollama /api/chat protocol identifies which tool produced a result via a name field on the tool-role message (no tool_call_id — Ollama doesn't assign call IDs). Without it the example works for a single tool, but adding a second tool later would produce ambiguous attribution and confuse the model:

Suggested change

	messages.push({ role: "tool", content: result });
	messages.push({ role: "tool", content: result, name: call.function.name } as ChatMessage);

You'll need to add name?: string to the ChatMessage interface at line 105 to make this typecheck.

[M64GitHub]

Deliberately leaving this one out. This example has a single tool, and result attribution only matters once there are two or more — adding a field for a case the example doesn't demonstrate cuts against its 'minimal / as-simple-as-possible' goal (it's conference-teaching code). Also worth noting: the suggested name is the OpenAI-compat field; this code talks to Ollama's native /api/chat, where the tool-result attribution field is tool_name. So the multi-tool version of this (planned for a separate standalone repo) will add tool_name then, when it actually has multiple tools to disambiguate. Verified the single-tool flow works correctly without it.