Refactor ToolContext to parity class taking a list of Tool | Toolset

[toubatbrian]

Summary

Refactor Agent({ tools }) to accept a list of FunctionTool | ProviderDefinedTool | Toolset entries instead of the legacy Record<string, FunctionTool> map, matching the shape of the Python ToolContext. llm.tool({ ... }) now requires an explicit name. This is a breaking change with no backward compatibility shim.

Key changes

• llm.tool({ name, ... }) — name is now required and stored on the returned FunctionTool.
• Toolset base class — stateful container for a group of tools, with id, tools: readonly Tool[], and overridable setup() / aclose() lifecycle hooks.
• ToolContext is a class with Python parity:
  • constructor takes readonly (FunctionTool | ProviderDefinedTool | Toolset)[]
  • functionTools (map view, includes tools flattened from toolsets)
  • providerTools, toolsets, tools (original list)
  • flatten(), getFunctionTool(name), updateTools(), copy(), equals()
  • ToolContext.empty()
  • Internal storage mirrors Python: original _tools list + denormalized _functionToolsMap + _providerTools + _toolsets. Tools from a Toolset are recursively flattened into the function/provider collections; duplicate function names referencing different instances throw.
• Agent({ tools }) and agent.updateTools(tools) now accept the same list shape.
• All callers across agents/, plugins/, and examples/ updated. Tests refreshed and ToolContext-class coverage added in tool_context.test.ts.

Usage

const getWeather = llm.tool({
  name: 'getWeather',
  description: 'Get the weather for a location.',
  parameters: z.object({ location: z.string() }),
  execute: async ({ location }) => `Sunny in ${location}`,
});

const locationTools = new llm.Toolset({
  id: 'location_tools',
  tools: [getWeather],
});

new voice.Agent({
  instructions: 'You are a helpful assistant.',
  tools: [getWeather, locationTools],
});

Test Plan

• pnpm build — all 32 packages build
• pnpm test agents/src/llm/tool_context.test.ts agents/src/llm/tool_context.type.test.ts agents/src/voice/agent.test.ts agents/src/voice/agent_activity.test.ts agents/src/voice/generation_tools.test.ts — green
• pnpm lint — clean (only pre-existing warnings remain)
• pnpm format:check — clean
• Remaining failures in the full pnpm test run all require external API keys / network and pre-date this change.

Notes

• The standalone Toolset PR (Add base Toolset support  #1485) will be rebased on top of this once this lands.
• A migration helper toolListFromRecord(map) is exported for any external code still holding the legacy map shape — it returns a list and stamps the map key onto unnamed tools.

[changeset-bot]

🦋 Changeset detected

Latest commit: 1c7c753

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 31 packages

Name	Type
@livekit/agents	Major
@livekit/agents-plugin-anam	Major
@livekit/agents-plugin-assemblyai	Major
@livekit/agents-plugin-baseten	Major
@livekit/agents-plugin-bey	Major
@livekit/agents-plugin-cartesia	Major
@livekit/agents-plugin-cerebras	Major
@livekit/agents-plugin-deepgram	Major
@livekit/agents-plugin-elevenlabs	Major
@livekit/agents-plugin-fishaudio	Major
@livekit/agents-plugin-google	Major
@livekit/agents-plugin-hedra	Major
@livekit/agents-plugin-hume	Major
@livekit/agents-plugin-inworld	Major
@livekit/agents-plugin-lemonslice	Major
@livekit/agents-plugin-liveavatar	Major
@livekit/agents-plugin-livekit	Major
@livekit/agents-plugin-minimax	Major
@livekit/agents-plugin-mistral	Major
@livekit/agents-plugin-mistralai	Major
@livekit/agents-plugin-neuphonic	Major
@livekit/agents-plugin-openai	Major
@livekit/agents-plugin-phonic	Major
@livekit/agents-plugin-resemble	Major
@livekit/agents-plugin-rime	Major
@livekit/agents-plugin-runway	Major
@livekit/agents-plugin-sarvam	Major
@livekit/agents-plugin-silero	Major
@livekit/agents-plugins-test	Major
@livekit/agents-plugin-trugen	Major
@livekit/agents-plugin-xai	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ toubatbrian
❌ claude
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

[devin-ai-integration]

🟡 providerTools getter exposes internal array without copying, contrary to JSDoc and other getters

The providerTools getter at agents/src/llm/tool_context.ts:254 returns this._providerTools directly (the internal mutable array), while the JSDoc says "A copy of all provider tools". In contrast, the functionTools getter (line 249) creates a new object via Object.fromEntries, and the tools getter (line 270) spreads into a new array. If any caller mutates the returned array (e.g. .push()), it silently corrupts the ToolContext's internal state, which would affect equals() and flatten() until the next updateTools() call.

Suggested change

	get providerTools(): ProviderDefinedTool[] {
	return this._providerTools;
	}
	get providerTools(): ProviderDefinedTool[] {
	return [...this._providerTools];
	}

---

Was this helpful? React with 👍 or 👎 to provide feedback.