feat: add optional You.com search integration

.changeset/feat-youcom-search-integration.md

@@ -0,0 +1,7 @@
+---
+"voltagent-example-with-youcom-search": patch
+---
+
+feat: add optional You.com search integration example
+
+Adds a comprehensive example demonstrating You.com web search and content extraction integration with VoltAgent. Includes authenticated API usage, error handling, and documentation for web research workflows.

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

@@ -0,0 +1,7 @@
+# You.com API Configuration (Required)
+# Get your API key from: https://api.you.com/
+# This example requires YDC_API_KEY for both search and content extraction.
+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,124 @@
+# 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
+- **API key authentication**: Requires You.com API key for access
+- **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` - Required You.com API key
+
+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 Requirements
+
+You.com requires an API key for both search and content extraction. Get your `YDC_API_KEY` at: https://api.you.com/
+
+With a valid API key, you get:
+
+- Access to You.com's search and content extraction APIs
+- Comprehensive search results with metadata
+- Content extraction from any accessible URL
+- Rate-limited but reliable access
+
+## 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, youContentsTool } from "./src/tools/you-search-tool.js";
+
+const agent = new Agent({
+  name: "You.com Search Agent",
+  tools: [youSearchTool, youContentsTool],
+  // ... 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.
+Queries and URLs are not echoed back in logs or tool 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
+- Sensitive information in queries and URLs is not logged

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 { youContentsTool, 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
+- Requires YDC_API_KEY for 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, youContentsTool],
+  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, youContentsTool } from "./you-search-tool.js";