diff --git a/guides/actions.mdx b/guides/actions.mdx index f9a9625..0a91305 100644 --- a/guides/actions.mdx +++ b/guides/actions.mdx @@ -5,27 +5,34 @@ description: "Extend your Guru's capabilities with external API calls and tool i ## Overview -Actions extend your Guru's capabilities by connecting it to external APIs and services. When users ask questions that require real-time data, your Guru can automatically trigger these actions to fetch information and provide up-to-date responses. +Actions extend your Guru's capabilities by executing custom Python code or making external API calls. When users ask questions that require real-time data or custom processing, your Guru can automatically trigger these actions to fetch information and provide up-to-date responses. -### What Actions Enable + + Actions + + +Actions support two types: +- **Python Code:** Execute custom Python scripts in isolated containers for data processing, API integrations, and custom logic. +- **API Call:** Make HTTP requests to external APIs and services. -Actions transform your Guru into a dynamic assistant that can: -- **Fetch real-time data** from external APIs -- **Retrieve current information** like weather, stock prices, or user details -- **Integrate with third-party tools** and platforms +Actions transform your Guru into a dynamic assistant that can -### Action Limits +- fetch real-time data +- process data with custom scripts +- retrieve current information +- integrate with third-party tools -Each Guru has a limit on the number of actions (e.g., "1 of 10 actions used"). +Each Guru has a limit on the number of actions (e.g., "5 of 10 actions used"). ## How Actions Work Actions use an intelligent trigger system: -1. **Condition Prompt Evaluation**: The Guru checks if the user's question matches your defined conditions (based on **Condition Prompt**) +1. **Condition Prompt Evaluation**: The Guru checks if the user's question matches your defined conditions (based on **When to Trigger This Action**) 2. **Parameter Extraction**: Parameters are extracted from the user's question based on your descriptions 3. **Execution Decision**: The action runs only if all required parameters can be extracted (or have default values) -4. **API Call and Response**: The configured API call is made, and the **Usage Prompt** instructs the AI how to use the response +4. **Execution**: Python code runs in an isolated container, or an API call is made to the configured endpoint +5. **Response Handling**: The **Usage Instructions** guide the AI on how to interpret and present the results ## Creating an Action @@ -33,86 +40,111 @@ Actions use an intelligent trigger system: Empty Actions -The action creation process consists of two main steps: General Configuration and API Configuration. +The action creation process consists of three main steps: -### Step 1: General Configuration +1. Basic Information and Parameters +2. Action Type Configuration (Python Code or API Call) +3. Usage Instructions and Testing + +### Basic Information and Parameters - Action General Configuration + Action Basic Configuration -#### Action Name -Provide a descriptive name that appears in your actions list. - -#### Description -Explain what this action does and when it should be used. - -#### Condition Prompt -Describe when this action should be triggered. Be specific to ensure it only runs when appropriate. - -**Example**: "When a question about a Github user is asked." +- **Action Name**: Provide a descriptive name that appears in your actions list +- **When to Trigger This Action**: Be specific about keywords, patterns, or user intents to ensure it only runs when appropriate (e.g., "When the user wants to guess the secret number") - Action Parameters Configuration + Action Parameters Configuration -#### Parameters Configuration +Define what information to extract from user questions. Parameters can be used like below: +- **API Call**: Use them in your API endpoint, headers, body using `{parameter_name}` syntax +- **Python Code**: Use them as environment variables via `os.environ.get()` + Each parameter includes: -- **Parameter Name**: Use only letters and underscores (e.g., `username`, `user_id`) +- **Name**: Use only letters and underscores (e.g., `username`, `user_id`). Cannot conflict with secret names. - **Type**: Choose from String (text), Number (numeric), or Boolean (true/false) -- **Description**: Clear description for parameter extraction from user questions +- **What to Extract**: Clear description for parameter extraction from user questions - **Required**: Check if essential for the action to work - **Default Value**: Optional fallback when parameter can't be extracted -### Step 2: API Configuration +### Usage Instructions and Testing - API Configuration Setup + Usage Instructions Configuration -#### HTTP Method -Select from `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. +- **Usage Instructions**: Provide instructions for how the AI should interpret and use the response data (API response or Python stdout) + - Example: "Use stdout to decide if the guess was correct" + - Example: "Extract the user's name and bio from the JSON response and present this information in a clear summary" +- **Testing**: Use the "Test Action" button to verify your configuration + - If required parameters exist, you'll be prompted to provide test values + - Test results show success status, response data, and execution details -#### Endpoint URL -Enter the API endpoint. It supports parameters like `{param_name}` +## Action Types -**Example**: `https://api.github.com/users/{username}` +When creating an action, choose between: -#### Headers -Configure authentication or content type headers. It supports parameters like `{param_name}` +- **Python Code**: Execute custom Python scripts in isolated containers +- **API Call**: Make HTTP requests to external APIs and services -**Example**: `Authorization: Bearer {token}` - -#### Request Body (JSON) -For `POST`, `PUT`, and `PATCH` methods, include JSON payload. It supports parameters like `{param_name}` - -```json -{ - "query": "{search_term}", - "user_id": "{user_id}" -} -``` +### Python Code Actions - Usage Prompt Configuration + Python Code Configuration -#### Usage Prompt -Provide instructions for how the AI should interpret and use the API response data. +Execute custom Python code in isolated Docker containers. Secrets and parameters are injected as environment variables accessible via `os.environ.get()`. -**Example**: "Analyze the JSON of the given user and provide a summary of their GitHub profile information." +**Key Features:** +- Isolated execution (containers destroyed after use) +- Whitelisted libraries (requests, pandas, numpy, json, datetime, re, hashlib, base64, etc.) +- Results via stdout (automatically captured) +- 30-second timeout +- 128MB RAM limit + +**Example:** +```python +import os +import requests + +guess = int(os.environ.get('GUESS')) +secret_n = int(os.environ.get('TEST')) # Secret from Settings + +print(f'Guess == secret: {guess == secret_n}') +``` -#### Testing Your Action +**Available Libraries:** +- requests, pandas, numpy, json, datetime, re, hashlib, base64, uuid, secrets, and more +- **Restricted**: `os` only allows `os.getenv()` and `os.environ` access + +### API Call Actions + + + API Call Configuration + - Action Testing Results + API Call Request Body -Use the "Test Action" button to verify your configuration. If required parameters exist, you'll be prompted to provide test values. +- **HTTP Method**: Select from `GET`, `POST`, `PUT`, `PATCH`, `DELETE` +- **Endpoint URL**: Enter the API endpoint. Use `{parameter_name}` or `{SECRET_NAME}` to insert parameter/secret values + - Example: `https://api.github.com/users/{username}` +- **Headers**: Configure authentication or content type using `{parameter_name}` or `{SECRET_NAME}` syntax + - Example: `Authorization: Bearer {API_KEY}` +- **Request Body**: For `POST`, `PUT`, and `PATCH` methods, include JSON payload supporting `{parameter_name}` or `{SECRET_NAME}` syntax: -Test results show success status, response data, and HTTP status code. +```json +{ + "test": "{TEST}", + "new_address": "{new_address}" +} +``` ## Managing Actions @@ -120,63 +152,58 @@ Test results show success status, response data, and HTTP status code. Actions Management Dashboard -Once created, you can manage all your actions from the Actions dashboard: - -### Actions List -View all configured actions with their name, description, type ("API Call"), and status (Enabled/Disabled). - - -For now, only the "API Call" type is implemented. We are planning to add new types of actions in the future. - - -### Action Management Options +- View all configured actions with their name, type ("Python Code" or "API Call"), and status (Enabled/Disabled) +- Click the menu icon (⋮) next to any action to: + - **Edit**: Modify the action's configuration + - **Disable**: Temporarily disable without deleting + - **Delete**: Permanently remove the action Action Management Options -Click the menu icon (⋮) next to any action to: -- **Edit**: Modify the action's configuration -- **Disable**: Temporarily disable without deleting -- **Delete**: Permanently remove the action - -### Enabling and Disabling Actions -Enable or disable actions at any time. Disabled actions won't be triggered by user questions. +- Enable or disable actions at any time +- Disabled actions won't be triggered by user questions +- **Note**: If a secret used by an action is deleted, that action will be automatically disabled ## Usage in the Answer -Actions used in the answer are shown as below with the action name: +Actions used in the answer are shown with the action name: Action Reference -## Common Mistakes to Avoid +## Secrets Management -### 1. Vague Condition Prompts -❌ **Poor**: "When asking about data" +Secrets are encrypted credentials (API keys, tokens, passwords) configured in Guru Settings → Secrets. They can be used in both Python Code and API Call actions. -✅ **Good**: "When asking about current weather conditions for a specific location" + + Secrets + -### 2. Inadequate Parameter Descriptions -❌ **Poor**: Parameter name: `id`, Description: "The ID" +**Key Points:** +- Secrets are encrypted at rest (AES-256) and masked in all output +- Access secrets in Python via `os.environ.get('SECRET_NAME')` +- Use secrets in API calls with `{SECRET_NAME}` syntax +- Secret names cannot conflict with parameter names +- Deleting a secret automatically disables all actions using it -✅ **Good**: Parameter name: `user_id`, Description: "The unique identifier for the GitHub user whose profile information is being requested" +**Example Usage:** +- **Python**: `api_key = os.environ.get('STRIPE_API_KEY')` +- **API Call**: `Authorization: Bearer {STRIPE_API_KEY}` -### 3. Incomplete Usage Prompts -❌ **Poor**: "Use the response data" +## Common Mistakes to Avoid -✅ **Good**: "Extract the user's name, bio, and public repository count from the JSON response and present this information in a clear, formatted summary" +**Vague Condition Prompts**: ❌ "When asking about data" → ✅ "When asking about current weather conditions for a specific location" -### 4. Not Testing Actions -❌ **Poor**: Enabling actions without testing them first +**Inadequate Parameter Descriptions**: ❌ Parameter name: `id`, Description: "The ID" → ✅ Parameter name: `user_id`, Description: "The unique identifier for the GitHub user whose profile information is being requested" -✅ **Good**: Always test actions with various parameter combinations before enabling +**Incomplete Usage Instructions**: ❌ "Use the response data" → ✅ "Extract the user's name, bio, and public repository count from the JSON response and present this information in a clear, formatted summary" -### 5. Overly Complex Actions -❌ **Poor**: Creating actions that try to do too many things at once +**Not Testing Actions**: ❌ Enabling actions without testing them first → ✅ Always test actions with various parameter combinations before enabling -✅ **Good**: Keep actions focused on a single, specific task +**Overly Complex Actions**: ❌ Creating actions that try to do too many things at once → ✅ Keep actions focused on a single, specific task ## Next Steps diff --git a/images/guides/actions/actions-page.png b/images/guides/actions/actions-page.png new file mode 100644 index 0000000..60167e7 Binary files /dev/null and b/images/guides/actions/actions-page.png differ diff --git a/images/guides/actions/api-call-settings-1.png b/images/guides/actions/api-call-settings-1.png new file mode 100644 index 0000000..9dee977 Binary files /dev/null and b/images/guides/actions/api-call-settings-1.png differ diff --git a/images/guides/actions/api-call-settings-2.png b/images/guides/actions/api-call-settings-2.png new file mode 100644 index 0000000..d47f217 Binary files /dev/null and b/images/guides/actions/api-call-settings-2.png differ diff --git a/images/guides/actions/basic-action-fields.png b/images/guides/actions/basic-action-fields.png new file mode 100644 index 0000000..8094f7e Binary files /dev/null and b/images/guides/actions/basic-action-fields.png differ diff --git a/images/guides/actions/parameters.png b/images/guides/actions/parameters.png new file mode 100644 index 0000000..b97042e Binary files /dev/null and b/images/guides/actions/parameters.png differ diff --git a/images/guides/actions/python.png b/images/guides/actions/python.png new file mode 100644 index 0000000..ab9c88b Binary files /dev/null and b/images/guides/actions/python.png differ diff --git a/images/guides/actions/secrets.png b/images/guides/actions/secrets.png new file mode 100644 index 0000000..81c3ca5 Binary files /dev/null and b/images/guides/actions/secrets.png differ diff --git a/images/guides/actions/stage1-1.png b/images/guides/actions/stage1-1.png deleted file mode 100644 index 1b267b6..0000000 Binary files a/images/guides/actions/stage1-1.png and /dev/null differ diff --git a/images/guides/actions/stage1-2.png b/images/guides/actions/stage1-2.png deleted file mode 100644 index 3c7f746..0000000 Binary files a/images/guides/actions/stage1-2.png and /dev/null differ diff --git a/images/guides/actions/stage2-1.png b/images/guides/actions/stage2-1.png deleted file mode 100644 index 13142a5..0000000 Binary files a/images/guides/actions/stage2-1.png and /dev/null differ diff --git a/images/guides/actions/stage2-2.png b/images/guides/actions/stage2-2.png deleted file mode 100644 index f24d46d..0000000 Binary files a/images/guides/actions/stage2-2.png and /dev/null differ diff --git a/images/guides/actions/stage2-3.png b/images/guides/actions/stage2-3.png deleted file mode 100644 index 0a55235..0000000 Binary files a/images/guides/actions/stage2-3.png and /dev/null differ diff --git a/images/guides/actions/usage-instructions-with-test.png b/images/guides/actions/usage-instructions-with-test.png new file mode 100644 index 0000000..0da338f Binary files /dev/null and b/images/guides/actions/usage-instructions-with-test.png differ