documentation for credentials manager

DEVELOPER.md

@@ -83,6 +83,17 @@ The `setup` script performs these actions:
 2. Generates `.env` files from your `config.yaml`
 3. Reports any issues
 
+### AI Agent Tools (Optional)
+
+If working with the agent framework:
+
+```bash
+# Set up aden-tools credentials
+cd aden-tools
+cp .env.example .env
+# Edit .env with your ANTHROPIC_API_KEY and BRAVE_SEARCH_API_KEY
+```
+
 ### Verify Setup
 
 ```bash

aden-tools/README.md

@@ -13,6 +13,27 @@ For development:
 pip install -e "aden-tools[dev]"
 ```
 
+## Environment Setup
+
+Some tools require API keys to function. Copy the example file and add your credentials:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required For | Get Key |
+|----------|--------------|---------|
+| `ANTHROPIC_API_KEY` | MCP server startup, LLM nodes | [console.anthropic.com](https://console.anthropic.com/) |
+| `BRAVE_SEARCH_API_KEY` | `web_search` tool | [brave.com/search/api](https://brave.com/search/api/) |
+
+Alternatively, export as environment variables:
+```bash
+export ANTHROPIC_API_KEY=your-key-here
+export BRAVE_SEARCH_API_KEY=your-key-here
+```
+
+See [.env.example](.env.example) for details.
+
 ## Quick Start
 
 ### As an MCP Server

core/MCP_BUILDER_TOOLS_GUIDE.md

@@ -332,3 +332,59 @@ You can register any MCP server that follows the Model Context Protocol specific
 - Verify you registered at least one MCP server
 - Check `get_session_status` to see `mcp_servers_count > 0`
 - Re-export the agent after registering servers
+
+## Credential Validation
+
+When adding nodes with tools that require API keys (like `web_search`), the agent builder automatically validates that the required credentials are available.
+
+### How It Works
+
+When you call `add_node` or `update_node` with a `tools` parameter, the agent builder:
+
+1. Checks which tools require credentials (e.g., `web_search` requires `BRAVE_SEARCH_API_KEY`)
+2. Validates those credentials are set in the environment or `.env` file
+3. Returns an error if any credentials are missing
+
+### Missing Credentials Error
+
+If credentials are missing, you'll receive a response like:
+
+```json
+{
+  "valid": false,
+  "errors": ["Missing credentials for tools: ['BRAVE_SEARCH_API_KEY']"],
+  "missing_credentials": [
+    {
+      "credential": "brave_search",
+      "env_var": "BRAVE_SEARCH_API_KEY",
+      "tools_affected": ["web_search"],
+      "help_url": "https://brave.com/search/api/",
+      "description": "API key for Brave Search"
+    }
+  ],
+  "action_required": "Add the credentials to your .env file and retry",
+  "example": "Add to .env:\nBRAVE_SEARCH_API_KEY=your_key_here",
+  "message": "Cannot add node: missing API credentials. Add them to .env and retry this command."
+}
+```
+
+### Fixing Credential Errors
+
+1. Get the required API key from the URL in `help_url`
+2. Add it to your environment:
+   ```bash
+   # Option 1: Export directly
+   export BRAVE_SEARCH_API_KEY=your-key-here
+
+   # Option 2: Add to aden-tools/.env
+   echo "BRAVE_SEARCH_API_KEY=your-key-here" >> aden-tools/.env
+   ```
+3. Retry the `add_node` command
+
+### Required Credentials by Tool
+
+| Tool | Credential | Get Key |
+|------|------------|---------|
+| `web_search` | `BRAVE_SEARCH_API_KEY` | [brave.com/search/api](https://brave.com/search/api/) |
+
+Note: The MCP server itself requires `ANTHROPIC_API_KEY` at startup for LLM operations.

docs/getting-started.md

@@ -97,6 +97,26 @@ hive/
 └── config.yaml         # Application configuration
 ```
 
+## AI Agent Tools Setup (Optional)
+
+If you're using the AI agent framework with aden-tools:
+
+```bash
+# 1. Navigate to aden-tools
+cd aden-tools
+
+# 2. Copy environment template
+cp .env.example .env
+
+# 3. Add your API keys to .env
+# - ANTHROPIC_API_KEY: Required for LLM operations
+# - BRAVE_SEARCH_API_KEY: Required for web search tool
+```
+
+Get your API keys:
+- **Anthropic**: [console.anthropic.com](https://console.anthropic.com/)
+- **Brave Search**: [brave.com/search/api](https://brave.com/search/api/)
+
 ## Next Steps
 
 1. **Configure the Application**: See [Configuration Guide](configuration.md)