feat: add toolkit create reasoning tools

.changeset/great-foxes-see.md

@@ -0,0 +1,120 @@
+---
+"@voltagent/core": minor
+---
+
+## Introducing Toolkits for Better Tool Management
+
+Managing related tools and their instructions is now simpler with `Toolkit`s.
+
+**Motivation:**
+
+- Defining shared instructions for multiple related tools was cumbersome.
+- The logic for deciding which instructions to add to the agent's system prompt could become complex.
+- We wanted a cleaner way to group tools logically.
+
+**What's New: The `Toolkit`**
+
+A `Toolkit` bundles related tools and allows defining shared `instructions` and an `addInstructions` flag _at the toolkit level_.
+
+```typescript
+// packages/core/src/tool/toolkit.ts
+export type Toolkit = {
+  /**
+   * Unique identifier name for the toolkit.
+   */
+  name: string;
+  /**
+   * A brief description of what the toolkit does. Optional.
+   */
+  description?: string;
+  /**
+   * Shared instructions for the LLM on how to use the tools within this toolkit.
+   * Optional.
+   */
+  instructions?: string;
+  /**
+   * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+   * Defaults to false.
+   */
+  addInstructions?: boolean;
+  /**
+   * An array of Tool instances that belong to this toolkit.
+   */
+  tools: Tool<any>[];
+};
+```
+
+**Key Changes to Core:**
+
+1.  **`ToolManager` Upgrade:** Now manages both `Tool` and `Toolkit` objects.
+2.  **`AgentOptions` Update:** The `tools` option accepts `(Tool<any> | Toolkit)[]`.
+3.  **Simplified Instruction Handling:** `Agent` now only adds instructions from `Toolkit`s where `addInstructions` is true.
+
+This change leads to a clearer separation of concerns, simplifies the agent's internal logic, and makes managing tool instructions more predictable and powerful.
+
+### New `createToolkit` Helper
+
+We've also added a helper function, `createToolkit`, to simplify the creation of toolkits. It provides default values and basic validation:
+
+```typescript
+// packages/core/src/tool/toolkit.ts
+export const createToolkit = (options: Toolkit): Toolkit => {
+  if (!options.name) {
+    throw new Error("Toolkit name is required");
+  }
+  if (!options.tools || options.tools.length === 0) {
+    console.warn(`Toolkit '${options.name}' created without any tools.`);
+  }
+
+  return {
+    name: options.name,
+    description: options.description || "", // Default empty description
+    instructions: options.instructions,
+    addInstructions: options.addInstructions || false, // Default to false
+    tools: options.tools || [], // Default to empty array
+  };
+};
+```
+
+**Example Usage:**
+
+```typescript
+import { createTool, createToolkit } from "@voltagent/core";
+import { z } from "zod";
+
+// Define some tools first
+const getWeather = createTool({
+  name: "getWeather",
+  description: "Gets the weather for a location.",
+  schema: z.object({ location: z.string() }),
+  run: async ({ location }) => ({ temperature: "25C", condition: "Sunny" }),
+});
+
+const searchWeb = createTool({
+  name: "searchWeb",
+  description: "Searches the web for a query.",
+  schema: z.object({ query: z.string() }),
+  run: async ({ query }) => ({ results: ["Result 1", "Result 2"] }),
+});
+
+// Create a toolkit using the helper
+const webInfoToolkit = createToolkit({
+  name: "web_information",
+  description: "Tools for getting information from the web.",
+  instructions: "Use these tools to find current information online.",
+  addInstructions: true, // Add the instructions to the system prompt
+  tools: [getWeather, searchWeb],
+});
+
+console.log(webInfoToolkit);
+/*
+Output:
+{
+  name: 'web_information',
+  description: 'Tools for getting information from the web.',
+  instructions: 'Use these tools to find current information online.',
+  addInstructions: true,
+  tools: [ [Object Tool: getWeather], [Object Tool: searchWeb] ]
+}
+*/
+```

.changeset/young-moments-sink.md

@@ -0,0 +1,54 @@
+---
+"@voltagent/core": minor
+---
+
+## Introducing Reasoning Tools Helper
+
+This update introduces a new helper function, `createReasoningTools`, to easily add step-by-step reasoning capabilities to your agents. #24
+
+### New `createReasoningTools` Helper
+
+**Feature:** Easily add `think` and `analyze` tools for step-by-step reasoning.
+
+We've added a new helper function, `createReasoningTools`, which makes it trivial to equip your agents with structured thinking capabilities, similar to patterns seen in advanced AI systems.
+
+- **What it does:** Returns a pre-configured `Toolkit` named `reasoning_tools`.
+- **Tools included:** Contains the `think` tool (for internal monologue/planning) and the `analyze` tool (for evaluating results and deciding next steps).
+- **Instructions:** Includes detailed instructions explaining how the agent should use these tools iteratively to solve problems. You can choose whether these instructions are automatically added to the system prompt via the `addInstructions` option.
+
+```typescript
+import { createReasoningTools, type Toolkit } from "@voltagent/core";
+
+// Get the reasoning toolkit (with instructions included in the system prompt)
+const reasoningToolkit: Toolkit = createReasoningTools({ addInstructions: true });
+
+// Get the toolkit without automatically adding instructions
+const reasoningToolkitManual: Toolkit = createReasoningTools({ addInstructions: false });
+```
+
+### How to Use Reasoning Tools
+
+Pass the `Toolkit` object returned by `createReasoningTools` directly to the agent's `tools` array.
+
+```typescript
+// Example: Using the new reasoning tools helper
+import { Agent, createReasoningTools, type Toolkit } from "@voltagent/core";
+import { VercelAIProvider } from "@voltagent/vercel-ai";
+import { openai } from "@ai-sdk/openai";
+
+const reasoningToolkit: Toolkit = createReasoningTools({
+  addInstructions: true,
+});
+
+const agent = new Agent({
+  name: "MyThinkingAgent",
+  description: "An agent equipped with reasoning tools.",
+  llm: new VercelAIProvider(),
+  model: openai("gpt-4o-mini"),
+  tools: [reasoningToolkit], // Pass the toolkit
+});
+
+// Agent's system message will include reasoning instructions.
+```
+
+This change simplifies adding reasoning capabilities to your agents.

examples/base/src/index.ts

@@ -1,17 +1,26 @@
-import { VoltAgent, Agent } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { Agent, MCPConfiguration } from "@voltagent/core";
 import { VercelAIProvider } from "@voltagent/vercel-ai";
 
-import { openai } from "@ai-sdk/openai";
+const mcpConfig = new MCPConfiguration({
+  servers: {
+    github: {
+      type: "http",
+      url: "https://mcp.composio.dev/github/mealy-few-wire-UfUhSQ?agent=cursor",
+    },
+  },
+});
 
 const agent = new Agent({
-  name: "Asistant",
-  description: "A helpful assistant that answers questions without using tools",
+  name: "GitHub Starrer Agent",
+  description: "You help users star GitHub repositories",
   llm: new VercelAIProvider(),
   model: openai("gpt-4o-mini"),
+  tools: await mcpConfig.getTools(),
 });
 
-new VoltAgent({
-  agents: {
-    agent,
-  },
-});
+const result = await agent.streamText("Please star the repository 'composiohq/composio'");
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}

examples/with-thinking-tool/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.DS_Store
+.env 

examples/with-thinking-tool/README.md

@@ -0,0 +1,72 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1800" alt="435380213-b6253409-8741-462b-a346-834cd18565a9" src="https://github.com/user-attachments/assets/452a03e7-eeda-4394-9ee7-0ffbcf37245c" />
+</a>
+
+<br/>
+<br/>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a> |
+    <a href="https://s.voltagent.dev/discord">Discord</a> |
+    <a href="https://voltagent.dev/blog/">Blog</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+    <strong>VoltAgent Example: Using Reasoning Tools (`think` & `analyze`)</strong><br>
+This example demonstrates how to equip a VoltAgent with `think` and `analyze` tools to enable step-by-step reasoning and analysis during task execution.
+    <br />
+    <br />
+</div>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev)
+
+</div>
+
+<br/>
+
+## VoltAgent: With Thinking Tools Example
+
+This example showcases how to integrate the `think` and `analyze` tools from `@voltagent/core` into an agent. These tools allow the agent to perform structured reasoning:
+
+- **`think`**: Acts as a scratchpad for the agent to break down problems, plan steps, and explain its reasoning before taking action.
+- **`analyze`**: Allows the agent to evaluate the results of its actions or thoughts and decide on the next step (continue, validate, or provide a final answer).
+
+By using these tools, agents can tackle more complex tasks, exhibit clearer thought processes, and potentially improve their accuracy and reliability.
+
+This example sets up a basic agent, includes the reasoning tools, and logs the reasoning steps emitted by the agent during its interaction.
+
+## Setup
+
+1.  **Clone the repository (if you haven't already):**
+    ```bash
+    git clone https://github.com/voltagent/voltagent.git
+    cd voltagent/examples/with-thinking-tool
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+3.  **Set up environment variables:**
+    Create a `.env` file in this directory (`examples/with-thinking-tool`) and add your OpenAI API key:
+    ```env
+    OPENAI_API_KEY=your_openai_api_key_here
+    ```
+
+## Run the Example
+
+```bash
+npm run dev
+```
+
+Observe the console output. You should see the agent's final response as well as the `ReasoningStep` objects logged whenever the agent uses the `think` or `analyze` tools.

examples/with-thinking-tool/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "voltagent-example-with-thinking-tool",
+  "private": true,
+  "keywords": [
+    "voltagent",
+    "ai",
+    "agent",
+    "reasoning",
+    "think",
+    "analyze"
+  ],
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.10",
+    "@voltagent/cli": "^0.1.2",
+    "@voltagent/core": "^0.1.5",
+    "@voltagent/vercel-ai": "^0.1.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

examples/with-thinking-tool/src/index.ts

@@ -0,0 +1,32 @@
+import { VoltAgent, Agent, createReasoningTools, type Toolkit } from "@voltagent/core";
+import { VercelAIProvider } from "@voltagent/vercel-ai";
+import { openai } from "@ai-sdk/openai";
+
+const reasoningToolkit: Toolkit = createReasoningTools({
+  addInstructions: true,
+});
+
+const agent = new Agent({
+  name: "ThinkingAssistant",
+  description: `
+  You are an AI assistant designed for complex problem-solving and structured reasoning.
+  You leverage internal 'think' and 'analyze' tools to methodically work through challenges.
+
+  Your process involves:
+  1.  **Understanding:** Using 'think' to clarify the goal, constraints, and break down the problem.
+  2.  **Planning:** Again using 'think', outlining sequential steps, identifying information needs, or exploring potential strategies before taking action (like calling other tools).
+  3.  **Analyzing:** Employing 'analyze' after gathering information or completing steps to evaluate progress, check if results meet requirements, and decide the next logical move (e.g., continue the plan, revise the plan, conclude).
+
+  Your aim is to provide well-reasoned, accurate, and complete answers by thinking through the process internally.
+  `,
+  llm: new VercelAIProvider(),
+  model: openai("gpt-4o-mini"),
+  tools: [reasoningToolkit],
+  markdown: true,
+});
+
+new VoltAgent({
+  agents: {
+    agent,
+  },
+});

examples/with-thinking-tool/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}