Commands

The Agent SDK provides built-in commands accessible via agent.commands in your handle function. These let users manage their workspace, toggle debug mode, and install MCP servers.

Using Commands

Commands are available on the AgentContext passed to your handle function. Route them however fits your platform:

handle: async (req, env, agent) => {
	const body = (await req.json()) as {
		userId: string;
		chatId: string;
		text: string;
	};

	// Check for command prefix
	if (body.text.startsWith("/")) {
		const [command, ...args] = body.text.slice(1).split(" ");

		switch (command) {
			case "reset":
				return Response.json({
					reply: await agent.commands.reset(body.userId, body.chatId),
				});
			case "debug":
				return Response.json({
					reply: await agent.commands.debug(body.userId, body.chatId),
				});
			case "tools":
				return Response.json({
					reply: await agent.commands.listTools(body.userId),
				});
			case "install":
				return Response.json({
					reply: await agent.commands.installMcp(
						body.userId,
						body.chatId,
						args[0],
					),
				});
			case "uninstall":
				return Response.json({
					reply: await agent.commands.uninstallMcp(body.userId, args[0]),
				});
		}
	}

	// Normal message handling
	// ...
};

Available Commands

reset

Deletes the user's workspace entirely, clearing conversation history, memory, and all settings.

const reply = await agent.commands.reset(userId, chatId);
// "Context cleared. Starting fresh."

debug

Toggles debug mode on the user's workspace. When enabled, internal processing details are visible.

const reply = await agent.commands.debug(userId, chatId);
// "Debug mode enabled. You'll see internal processing details."
// or
// "Debug mode disabled."

listTools

Lists all available tools -- built-in, custom, and MCP server tools.

const reply = await agent.commands.listTools(userId);
// "Available tools:\n- memory_set\n- memory_get\n- ..."

installMcp

Installs an MCP server by fetching its manifest from a URL. The manifest must expose a /manifest endpoint returning { name: string, tools: Array<{ name, description, parameters }> }.

const reply = await agent.commands.installMcp(
	userId,
	chatId,
	"https://mcp.example.com",
);
// 'Installed MCP server "weather" with tools: get_forecast, get_alerts'

uninstallMcp

Removes an installed MCP server by name.

const reply = await agent.commands.uninstallMcp(userId, "weather");
// 'Uninstalled MCP server "weather".'

AgentCommands Interface

interface AgentCommands {
	reset: (userId: string, chatId: string) => Promise<string>;
	debug: (userId: string, chatId: string) => Promise<string>;
	installMcp: (userId: string, chatId: string, url: string) => Promise<string>;
	uninstallMcp: (userId: string, name: string) => Promise<string>;
	listTools: (userId: string) => Promise<string>;
}

Commands return plain strings. It's up to your handle function to send the reply back to the user through your platform's messaging API.

Next Steps

createAgent() -- Access commands via agent.commands in your handler
Tools -- The tools listed by /tools
State & Workspaces -- What /reset deletes

Commands

On this page