From 64b9cced41e21e9c2db93b9faf50af285085138e Mon Sep 17 00:00:00 2001 From: Emart29 Date: Sun, 1 Mar 2026 13:33:00 +0100 Subject: [PATCH 1/2] docs(tools): add README for brevo, csv, runtime_logs, account_info tools - brevo_tool: Transactional email/SMS and contact management via Brevo API - csv_tool: Read, write, query CSV files with DuckDB SQL support - runtime_logs_tool: Query three-level runtime logging system - account_info_tool: Query connected accounts and identities --- .../tools/account_info_tool/README.md | 104 +++++++++++ tools/src/aden_tools/tools/csv_tool/README.md | 168 ++++++++++++++++++ .../tools/runtime_logs_tool/README.md | 121 +++++++++++++ 3 files changed, 393 insertions(+) create mode 100644 tools/src/aden_tools/tools/account_info_tool/README.md create mode 100644 tools/src/aden_tools/tools/csv_tool/README.md create mode 100644 tools/src/aden_tools/tools/runtime_logs_tool/README.md diff --git a/tools/src/aden_tools/tools/account_info_tool/README.md b/tools/src/aden_tools/tools/account_info_tool/README.md new file mode 100644 index 0000000000..7c80b14a77 --- /dev/null +++ b/tools/src/aden_tools/tools/account_info_tool/README.md @@ -0,0 +1,104 @@ +# Account Info Tool + +Query connected accounts and their identities at runtime. + +## Features + +- **get_account_info** - List connected accounts with provider and identity details + +## Overview + +This tool allows agents to discover which external accounts are connected and available for use. It queries the credential store to retrieve account metadata without exposing secrets. + +## Setup + +No additional configuration required. The tool reads from the configured credential store. + +## Usage Examples + +### List All Connected Accounts +```python +get_account_info() +``` + +Returns: +```python +{ + "accounts": [ + { + "account_id": "google_main", + "provider": "google", + "identity": "user@gmail.com" + }, + { + "account_id": "slack_workspace", + "provider": "slack", + "identity": "My Workspace" + } + ], + "count": 2 +} +``` + +### Filter by Provider +```python +get_account_info(provider="google") +``` + +Returns only Google-connected accounts: +```python +{ + "accounts": [ + { + "account_id": "google_main", + "provider": "google", + "identity": "user@gmail.com" + } + ], + "count": 1 +} +``` + +## API Reference + +### get_account_info + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| provider | str | No | Filter by provider type (e.g., "google", "slack") | + +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| accounts | list | List of connected account objects | +| count | int | Number of accounts returned | + +### Account Object + +| Field | Type | Description | +|-------|------|-------------| +| account_id | str | Unique identifier for the account | +| provider | str | Provider type (google, slack, github, etc.) | +| identity | str | Human-readable identity (email, username, workspace) | + +## Supported Providers + +Common providers that may appear: +- `google` - Google accounts (Gmail, Drive, Calendar) +- `slack` - Slack workspaces +- `github` - GitHub accounts +- `hubspot` - HubSpot CRM accounts +- `brevo` - Brevo email/SMS accounts +- And any other configured OAuth or API integrations + +## Error Handling +```python +{"accounts": [], "message": "No credential store configured"} +``` + +## Use Cases + +- **Multi-account workflows**: Determine which accounts are available before making API calls +- **User context**: Show users which accounts are connected in chat interfaces +- **Conditional logic**: Route tasks to different accounts based on availability diff --git a/tools/src/aden_tools/tools/csv_tool/README.md b/tools/src/aden_tools/tools/csv_tool/README.md new file mode 100644 index 0000000000..ec93fd0d6f --- /dev/null +++ b/tools/src/aden_tools/tools/csv_tool/README.md @@ -0,0 +1,168 @@ +# CSV Tool + +Read, write, and query CSV files with SQL support via DuckDB. + +## Features + +- **csv_read** - Read CSV file contents with pagination +- **csv_write** - Create new CSV files +- **csv_append** - Append rows to existing CSV files +- **csv_info** - Get CSV metadata without loading all data +- **csv_sql** - Query CSV files using SQL (powered by DuckDB) + +## Setup + +No API keys required. Files are accessed within the session sandbox. + +For SQL queries, DuckDB must be installed: +```bash +pip install duckdb +# or +uv pip install tools[sql] +``` + +## Usage Examples + +### Read a CSV File +```python +csv_read( + path="data/sales.csv", + workspace_id="ws_123", + agent_id="agent_1", + session_id="session_1", + limit=100, + offset=0 +) +``` + +### Write a New CSV +```python +csv_write( + path="output/report.csv", + workspace_id="ws_123", + agent_id="agent_1", + session_id="session_1", + columns=["name", "email", "score"], + rows=[ + {"name": "Alice", "email": "alice@example.com", "score": 95}, + {"name": "Bob", "email": "bob@example.com", "score": 87} + ] +) +``` + +### Append Rows +```python +csv_append( + path="data/log.csv", + workspace_id="ws_123", + agent_id="agent_1", + session_id="session_1", + rows=[ + {"timestamp": "2024-01-15", "event": "login", "user": "alice"} + ] +) +``` + +### Get File Info +```python +csv_info( + path="data/large_file.csv", + workspace_id="ws_123", + agent_id="agent_1", + session_id="session_1" +) +# Returns: columns, row count, file size (without loading all data) +``` + +### Query with SQL +```python +csv_sql( + path="data/sales.csv", + workspace_id="ws_123", + agent_id="agent_1", + session_id="session_1", + query="SELECT category, SUM(amount) as total FROM data GROUP BY category ORDER BY total DESC" +) +``` + +## API Reference + +### csv_read + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| path | str | Yes | Path to CSV file (relative to sandbox) | +| workspace_id | str | Yes | Workspace identifier | +| agent_id | str | Yes | Agent identifier | +| session_id | str | Yes | Session identifier | +| limit | int | No | Max rows to return (None = all) | +| offset | int | No | Rows to skip (default: 0) | + +### csv_write + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| path | str | Yes | Path for new CSV file | +| workspace_id | str | Yes | Workspace identifier | +| agent_id | str | Yes | Agent identifier | +| session_id | str | Yes | Session identifier | +| columns | list[str] | Yes | Column names for header | +| rows | list[dict] | Yes | Row data as dictionaries | + +### csv_append + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| path | str | Yes | Path to existing CSV file | +| workspace_id | str | Yes | Workspace identifier | +| agent_id | str | Yes | Agent identifier | +| session_id | str | Yes | Session identifier | +| rows | list[dict] | Yes | Rows to append | + +### csv_info + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| path | str | Yes | Path to CSV file | +| workspace_id | str | Yes | Workspace identifier | +| agent_id | str | Yes | Agent identifier | +| session_id | str | Yes | Session identifier | + +### csv_sql + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| path | str | Yes | Path to CSV file | +| workspace_id | str | Yes | Workspace identifier | +| agent_id | str | Yes | Agent identifier | +| session_id | str | Yes | Session identifier | +| query | str | Yes | SQL query (table name is `data`) | + +## SQL Query Examples +```sql +-- Filter rows +SELECT * FROM data WHERE status = 'pending' + +-- Aggregate data +SELECT category, COUNT(*) as count, AVG(price) as avg_price +FROM data GROUP BY category + +-- Sort and limit +SELECT name, price FROM data ORDER BY price DESC LIMIT 5 + +-- Case-insensitive search +SELECT * FROM data WHERE LOWER(name) LIKE '%phone%' +``` + +**Note:** Only SELECT queries are allowed for security. + +## Error Handling +```python +{"error": "File not found: path/to/file.csv"} +{"error": "File must have .csv extension"} +{"error": "CSV file is empty or has no headers"} +{"error": "CSV parsing error: ..."} +{"error": "File encoding error: unable to decode as UTF-8"} +{"error": "DuckDB not installed. Install with: uv pip install duckdb"} +{"error": "Only SELECT queries are allowed for security reasons"} +``` diff --git a/tools/src/aden_tools/tools/runtime_logs_tool/README.md b/tools/src/aden_tools/tools/runtime_logs_tool/README.md new file mode 100644 index 0000000000..f7d7188ae2 --- /dev/null +++ b/tools/src/aden_tools/tools/runtime_logs_tool/README.md @@ -0,0 +1,121 @@ +# Runtime Logs Tool + +Query the three-level runtime logging system for agent execution history. + +## Features + +- **query_runtime_logs** - Level 1: Run summaries (did the graph succeed?) +- **query_runtime_log_details** - Level 2: Per-node results (which node failed?) +- **query_runtime_log_raw** - Level 3: Full step data (what exactly happened?) + +## Overview + +The runtime logging system captures agent execution at three levels of detail: + +| Level | Tool | Purpose | Data | +|-------|------|---------|------| +| L1 | `query_runtime_logs` | Run summaries | Success/failure, duration, entry point | +| L2 | `query_runtime_log_details` | Node-level results | Per-node outcomes, errors, retries | +| L3 | `query_runtime_log_raw` | Full step data | Complete execution trace, LLM calls | + +## Setup + +No API keys required. Logs are read from the agent's working directory. + +## Usage Examples + +### Get Run Summaries (Level 1) +```python +query_runtime_logs( + agent_work_dir="/path/to/agent/workdir", + limit=10 +) +``` + +Returns recent runs with: +- Run ID and session ID +- Start/end timestamps +- Success/failure status +- Entry point used +- Duration + +### Get Node Details (Level 2) +```python +query_runtime_log_details( + agent_work_dir="/path/to/agent/workdir", + run_id="run_20240115_143022" +) +``` + +Returns per-node execution details: +- Node ID and name +- Execution status (success/failure/skipped) +- Error messages if failed +- Retry count +- Input/output keys + +### Get Raw Step Data (Level 3) +```python +query_runtime_log_raw( + agent_work_dir="/path/to/agent/workdir", + run_id="run_20240115_143022", + node_id="gather_info" # Optional: filter by node +) +``` + +Returns complete execution trace: +- Every LLM call with prompts/responses +- Tool invocations and results +- State changes +- Timing information + +## API Reference + +### query_runtime_logs + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| agent_work_dir | str | Yes | Path to agent working directory | +| limit | int | No | Max runs to return (default: 20) | +| status | str | No | Filter by "success" or "failure" | + +### query_runtime_log_details + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| agent_work_dir | str | Yes | Path to agent working directory | +| run_id | str | Yes | Run ID from Level 1 query | +| node_id | str | No | Filter to specific node | + +### query_runtime_log_raw + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| agent_work_dir | str | Yes | Path to agent working directory | +| run_id | str | Yes | Run ID from Level 1 query | +| node_id | str | No | Filter to specific node | +| step_type | str | No | Filter by step type (llm_call, tool_call, etc.) | + +## Log Storage Locations +``` +{agent_work_dir}/ +├── sessions/{session_id}/logs/ # New location +│ ├── summary.json # L1: Run summary +│ ├── nodes.jsonl # L2: Node details +│ └── steps.jsonl # L3: Raw steps +└── runtime_logs/runs/{run_id}/ # Legacy location (deprecated) +``` + +## Error Handling +```python +{"error": "Agent work directory not found"} +{"error": "Run ID not found: run_xyz"} +{"error": "No logs available for this run"} +{"error": "Failed to parse log file"} +``` + +## Use Cases + +- **Debugging failed runs**: Start with L1 to find failures, drill into L2 for the failing node, then L3 for exact error +- **Performance analysis**: Use L1 durations to identify slow runs, L3 for detailed timing +- **Audit trails**: L3 provides complete execution history for compliance From 51fad5ef75ba40e43fd3fa5100e0d3adc3908704 Mon Sep 17 00:00:00 2001 From: hundao Date: Thu, 5 Mar 2026 18:42:12 +0800 Subject: [PATCH 2/2] docs: fix runtime_logs_tool README to match implementation - query_runtime_logs: add missing status values (degraded, in_progress, needs_attention) - query_runtime_log_details: add missing needs_attention_only parameter - query_runtime_log_raw: fix step_type -> step_index (int, not str) - Fix file names: nodes.jsonl -> details.jsonl, steps.jsonl -> tool_logs.jsonl - Fix error handling examples to match actual code --- .../aden_tools/tools/runtime_logs_tool/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tools/src/aden_tools/tools/runtime_logs_tool/README.md b/tools/src/aden_tools/tools/runtime_logs_tool/README.md index f7d7188ae2..785df74e93 100644 --- a/tools/src/aden_tools/tools/runtime_logs_tool/README.md +++ b/tools/src/aden_tools/tools/runtime_logs_tool/README.md @@ -77,7 +77,7 @@ Returns complete execution trace: |-----------|------|----------|-------------| | agent_work_dir | str | Yes | Path to agent working directory | | limit | int | No | Max runs to return (default: 20) | -| status | str | No | Filter by "success" or "failure" | +| status | str | No | Filter: "success", "failure", "degraded", "in_progress", "needs_attention" | ### query_runtime_log_details @@ -85,6 +85,7 @@ Returns complete execution trace: |-----------|------|----------|-------------| | agent_work_dir | str | Yes | Path to agent working directory | | run_id | str | Yes | Run ID from Level 1 query | +| needs_attention_only | bool | No | If true, only return flagged nodes (default: false) | | node_id | str | No | Filter to specific node | ### query_runtime_log_raw @@ -94,24 +95,23 @@ Returns complete execution trace: | agent_work_dir | str | Yes | Path to agent working directory | | run_id | str | Yes | Run ID from Level 1 query | | node_id | str | No | Filter to specific node | -| step_type | str | No | Filter by step type (llm_call, tool_call, etc.) | +| step_index | int | No | Specific step index, or -1 for all steps (default: -1) | ## Log Storage Locations ``` {agent_work_dir}/ ├── sessions/{session_id}/logs/ # New location │ ├── summary.json # L1: Run summary -│ ├── nodes.jsonl # L2: Node details -│ └── steps.jsonl # L3: Raw steps +│ ├── details.jsonl # L2: Node details +│ └── tool_logs.jsonl # L3: Raw steps └── runtime_logs/runs/{run_id}/ # Legacy location (deprecated) ``` ## Error Handling ```python -{"error": "Agent work directory not found"} -{"error": "Run ID not found: run_xyz"} -{"error": "No logs available for this run"} -{"error": "Failed to parse log file"} +{"runs": [], "total": 0, "message": "No runtime logs found"} +{"error": "No details found for run "} +{"error": "No tool logs found for run "} ``` ## Use Cases