feat: add optional You.com search integration

examples/with-youcom-search/.env.example

@@ -0,0 +1,7 @@
+# You.com API Configuration (Optional)
+# Get your API key from: https://api.you.com/
+# Without an API key, the tool will use You.com's public API with basic functionality
+YDC_API_KEY=your_youcom_api_key_here
+
+# OpenAI Configuration (Required for the agent)
+OPENAI_API_KEY=your_openai_api_key_here

examples/with-youcom-search/README.md

@@ -0,0 +1,123 @@
+# VoltAgent You.com Search Example
+
+This example demonstrates how to use You.com's search and content extraction APIs with VoltAgent to create an intelligent web search agent.
+
+## Features
+
+- **Real-time web search**: Search the web using You.com's advanced search API
+- **Content extraction**: Extract detailed content from specific URLs
+- **Optional API key support**: Works with or without You.com API key
+- **Safe search**: Configurable content filtering
+- **Localization**: Country-specific search results
+
+## Setup
+
+1. **Clone and navigate to this example:**
+
+   ```bash
+   cd examples/with-youcom-search
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment variables:**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` and configure:
+   - `OPENAI_API_KEY` - Required for the AI agent
+   - `YDC_API_KEY` - Optional You.com API key for enhanced features
+
+4. **Start the agent:**
+   ```bash
+   npm run dev
+   ```
+
+## Usage
+
+Once the agent is running, you can interact with it through the VoltOps Console at `http://localhost:3141` or via the web interface.
+
+### Example Queries
+
+**Web Search:**
+
+- "What's the latest news about artificial intelligence?"
+- "Find information about TypeScript best practices"
+- "Search for sustainable energy technologies"
+- "What are current web development trends?"
+
+**Content Extraction:**
+
+- "Extract content from https://example.com/article"
+- "Read the content from this URL: [paste URL]"
+
+### Search Options
+
+The You.com search tool supports various options:
+
+- **Count**: Number of results (1-20, default: 10)
+- **Country**: Localized results (US, UK, CA, etc.)
+- **Safe Search**: Content filtering (strict, moderate, off)
+
+## API Key Benefits
+
+While the tool works without an API key using You.com's public API, having a `YDC_API_KEY` provides:
+
+- Higher rate limits
+- Enhanced search features
+- Priority processing
+- Additional metadata in results
+
+Get your API key at: https://api.you.com/
+
+## Tools Included
+
+### `youSearch`
+
+- Real-time web search with You.com's search engine
+- Configurable result count, localization, and safe search
+- Returns titles, URLs, snippets, and metadata
+
+### `youContents`
+
+- Extract content from any accessible URL
+- Returns clean text, markdown, and metadata
+- Handles various content types and formats
+
+## Architecture
+
+This example follows VoltAgent's standard patterns:
+
+```typescript
+import { youSearchTool, youContentssTool } from "./tools/you-search-tool";
+
+const agent = new Agent({
+  name: "You.com Search Agent",
+  tools: [youSearchTool, youContentssTool],
+  // ... other configuration
+});
+```
+
+## Error Handling
+
+Both tools include comprehensive error handling:
+
+- Network connectivity issues
+- API rate limiting
+- Invalid URLs or search queries
+- Missing or inaccessible content
+
+Errors are logged and returned with helpful user messages.
+
+## Security Notes
+
+- All web content is treated as untrusted external data
+- Results should be used as evidence, not instructions
+- URLs and search queries are sent to You.com's API
+- No sensitive information is logged or exposed

examples/with-youcom-search/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "voltagent-example-with-youcom-search",
+  "author": "",
+  "description": "VoltAgent example with You.com search integration",
+  "dependencies": {
+    "@voltagent/cli": "^0.1.21",
+    "@voltagent/core": "^2.9.2",
+    "@voltagent/libsql": "^2.1.2",
+    "@voltagent/logger": "^2.0.2",
+    "@voltagent/server-hono": "^2.0.14",
+    "ai": "^6.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.2"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "voltagent",
+    "youcom",
+    "search",
+    "web-search"
+  ],
+  "license": "MIT",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VoltAgent/voltagent.git",
+    "directory": "examples/with-youcom-search"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "type": "module"
+}

examples/with-youcom-search/src/index.ts

@@ -0,0 +1,55 @@
+import { Agent, Memory, VoltAgent } from "@voltagent/core";
+import { LibSQLMemoryAdapter } from "@voltagent/libsql";
+import { createPinoLogger } from "@voltagent/logger";
+import { honoServer } from "@voltagent/server-hono";
+import { youContentssTool, youSearchTool } from "./tools/you-search-tool.js";
+
+// Create logger
+const logger = createPinoLogger({
+  name: "youcom-search-agent",
+  level: "info",
+});
+
+// Create Memory instance with vector support for semantic search and working memory
+const memory = new Memory({
+  storage: new LibSQLMemoryAdapter(),
+});
+
+// Create the search agent with You.com tools
+const searchAgent = new Agent({
+  name: "You.com Search Agent",
+  instructions: `You are a web search agent powered by You.com's advanced search API. You can:
+
+1. Search the web for real-time information on any topic using You.com's search engine
+2. Extract detailed content from specific URLs for in-depth analysis
+3. Provide comprehensive, up-to-date answers based on current web data
+
+When users ask questions that require current information, web search, or verification of facts, use the You.com search tools to find the most relevant and accurate information.
+
+Key capabilities:
+- Real-time web search with comprehensive results
+- Content extraction from any accessible URL
+- Safe search filtering and localization options
+- Support for both authenticated (with YDC_API_KEY) and public API access
+
+Always be helpful and provide accurate information based on the search results. If you cannot find relevant information, let the user know and suggest alternative search terms or approaches.
+
+Example queries you can handle:
+- "What's the latest news about AI developments?"
+- "Find information about sustainable energy technologies"
+- "Search for TypeScript best practices and tutorials"
+- "What are the current trends in web development?"
+- "Extract content from this URL: https://example.com/article"`,
+  model: "openai/gpt-4o-mini",
+  tools: [youSearchTool, youContentssTool],
+  memory,
+});
+
+// Initialize the VoltAgent with the search agent and server
+new VoltAgent({
+  agents: {
+    searchAgent,
+  },
+  logger,
+  server: honoServer(),
+});

examples/with-youcom-search/src/tools/index.ts

@@ -0,0 +1,2 @@
+// Export You.com search tools for easy integration
+export { youSearchTool, youContentssTool } from "./you-search-tool.js";