mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-27 17:36:23 +02:00
Update docs for API/CLI changes in 1.0 (#420)
* Update some API basics for the 0.23/1.0 API change
This commit is contained in:
cybermaggedon
GitHub
parent
b1a546e4d2
commit
cc224e97f6
69 changed files with 19981 additions and 407 deletions
283
docs/cli/tg-show-tools.md
Normal file
283
docs/cli/tg-show-tools.md
Normal file
|
|
@ -0,0 +1,283 @@
|
|||
# tg-show-tools
|
||||
|
||||
## Synopsis
|
||||
|
||||
```
|
||||
tg-show-tools [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
The `tg-show-tools` command displays the current agent tool configuration from TrustGraph. It retrieves and presents detailed information about all available tools that agents can use, including their descriptions, arguments, and parameter types.
|
||||
|
||||
This command is useful for:
|
||||
- Understanding available agent tools and their capabilities
|
||||
- Debugging agent tool configuration issues
|
||||
- Documenting the current tool set
|
||||
- Verifying tool definitions and argument specifications
|
||||
|
||||
The command queries the TrustGraph API to fetch the tool index and individual tool definitions, then presents them in a formatted table for easy reading.
|
||||
|
||||
## Options
|
||||
|
||||
- `-u, --api-url URL`
|
||||
- TrustGraph API URL to query for tool configuration
|
||||
- Default: `http://localhost:8088/` (or `TRUSTGRAPH_URL` environment variable)
|
||||
- Should point to a running TrustGraph API instance
|
||||
|
||||
- `-h, --help`
|
||||
- Show help message and exit
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Display all available agent tools using the default API URL:
|
||||
```bash
|
||||
tg-show-tools
|
||||
```
|
||||
|
||||
### Custom API URL
|
||||
|
||||
Display tools from a specific TrustGraph instance:
|
||||
```bash
|
||||
tg-show-tools -u http://trustgraph.example.com:8088/
|
||||
```
|
||||
|
||||
### Remote Instance
|
||||
|
||||
Query tools from a remote TrustGraph deployment:
|
||||
```bash
|
||||
tg-show-tools --api-url http://10.0.1.100:8088/
|
||||
```
|
||||
|
||||
### Using Environment Variable
|
||||
|
||||
Set the API URL via environment variable:
|
||||
```bash
|
||||
export TRUSTGRAPH_URL=http://production.trustgraph.com:8088/
|
||||
tg-show-tools
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
The command displays each tool in a detailed table format:
|
||||
```
|
||||
web-search:
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| id | web-search |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| name | Web Search |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| description | Search the web for information using a search engine |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| arg 0 | query: string |
|
||||
| | The search query to execute |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| arg 1 | max_results: integer |
|
||||
| | Maximum number of search results to return |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
|
||||
file-read:
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| id | file-read |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| name | File Reader |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| description | Read contents of a file from the filesystem |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
| arg 0 | path: string |
|
||||
| | Path to the file to read |
|
||||
+-------------+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
For each tool, the output includes:
|
||||
- **id**: Unique identifier for the tool
|
||||
- **name**: Human-readable name of the tool
|
||||
- **description**: Detailed description of what the tool does
|
||||
- **arg N**: Arguments the tool accepts, with name, type, and description
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Tool Inventory
|
||||
|
||||
Create a complete inventory of available tools:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "=== TrustGraph Agent Tools Inventory ==="
|
||||
echo "Generated on: $(date)"
|
||||
echo
|
||||
tg-show-tools > tools_inventory.txt
|
||||
echo "Inventory saved to tools_inventory.txt"
|
||||
```
|
||||
|
||||
### Tool Comparison
|
||||
|
||||
Compare tools across different environments:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "=== Development Tools ==="
|
||||
tg-show-tools -u http://dev.trustgraph.com:8088/ > dev_tools.txt
|
||||
echo
|
||||
echo "=== Production Tools ==="
|
||||
tg-show-tools -u http://prod.trustgraph.com:8088/ > prod_tools.txt
|
||||
echo
|
||||
diff dev_tools.txt prod_tools.txt
|
||||
```
|
||||
|
||||
### Tool Documentation
|
||||
|
||||
Generate documentation for agent tools:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "# Available Agent Tools" > AGENT_TOOLS.md
|
||||
echo "" >> AGENT_TOOLS.md
|
||||
echo "Generated on: $(date)" >> AGENT_TOOLS.md
|
||||
echo "" >> AGENT_TOOLS.md
|
||||
tg-show-tools >> AGENT_TOOLS.md
|
||||
```
|
||||
|
||||
### Tool Configuration Validation
|
||||
|
||||
Validate tool configuration after updates:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "Validating tool configuration..."
|
||||
if tg-show-tools > /dev/null 2>&1; then
|
||||
echo "✓ Tool configuration is valid"
|
||||
tool_count=$(tg-show-tools | grep -c "^[a-zA-Z].*:$")
|
||||
echo "✓ Found $tool_count tools"
|
||||
else
|
||||
echo "✗ Tool configuration validation failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The command handles various error conditions:
|
||||
|
||||
- **API connection errors**: If the TrustGraph API is unavailable
|
||||
- **Authentication errors**: If API access is denied
|
||||
- **Invalid configuration**: If tool configuration is malformed
|
||||
- **Network timeouts**: If API requests time out
|
||||
|
||||
Common error scenarios:
|
||||
```bash
|
||||
# API not available
|
||||
tg-show-tools -u http://invalid-host:8088/
|
||||
# Output: Exception: [Connection error details]
|
||||
|
||||
# Invalid API URL
|
||||
tg-show-tools --api-url "not-a-url"
|
||||
# Output: Exception: [URL parsing error]
|
||||
|
||||
# Configuration not found
|
||||
# Output: Exception: [Configuration retrieval error]
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### With Agent Configuration
|
||||
|
||||
Display tools alongside agent configuration:
|
||||
```bash
|
||||
echo "=== Agent Tools ==="
|
||||
tg-show-tools
|
||||
echo
|
||||
echo "=== Agent Configuration ==="
|
||||
tg-show-config
|
||||
```
|
||||
|
||||
### With Flow Analysis
|
||||
|
||||
Understand tools used in flows:
|
||||
```bash
|
||||
echo "=== Available Tools ==="
|
||||
tg-show-tools
|
||||
echo
|
||||
echo "=== Active Flows ==="
|
||||
tg-show-flows
|
||||
```
|
||||
|
||||
### With Prompt Analysis
|
||||
|
||||
Analyze tool usage in prompts:
|
||||
```bash
|
||||
echo "=== Agent Tools ==="
|
||||
tg-show-tools | grep -E "^[a-zA-Z].*:$"
|
||||
echo
|
||||
echo "=== Available Prompts ==="
|
||||
tg-show-prompts
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Regular Documentation**: Keep tool documentation updated
|
||||
2. **Version Control**: Track tool configuration changes
|
||||
3. **Testing**: Test tool functionality after configuration changes
|
||||
4. **Security**: Review tool permissions and capabilities
|
||||
5. **Monitoring**: Monitor tool usage and performance
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No Tools Displayed
|
||||
|
||||
If no tools are shown:
|
||||
1. Verify the TrustGraph API is running and accessible
|
||||
2. Check that tool configuration has been properly loaded
|
||||
3. Ensure the API URL is correct
|
||||
4. Verify network connectivity
|
||||
|
||||
### Incomplete Tool Information
|
||||
|
||||
If tool information is missing or incomplete:
|
||||
1. Check the tool configuration files
|
||||
2. Verify the tool index is properly maintained
|
||||
3. Ensure tool definitions are valid JSON
|
||||
4. Check for configuration loading errors
|
||||
|
||||
### Tool Configuration Errors
|
||||
|
||||
If tools are not working as expected:
|
||||
1. Validate tool definitions against the schema
|
||||
2. Check for missing or invalid arguments
|
||||
3. Verify tool implementation is available
|
||||
4. Review agent logs for tool execution errors
|
||||
|
||||
## Tool Management
|
||||
|
||||
### Adding New Tools
|
||||
|
||||
After adding new tools to the system:
|
||||
```bash
|
||||
# Verify the new tool appears
|
||||
tg-show-tools | grep "new-tool-name"
|
||||
|
||||
# Test the tool configuration
|
||||
tg-show-tools > current_tools.txt
|
||||
```
|
||||
|
||||
### Removing Tools
|
||||
|
||||
After removing tools:
|
||||
```bash
|
||||
# Verify the tool is no longer listed
|
||||
tg-show-tools | grep -v "removed-tool-name"
|
||||
|
||||
# Update tool documentation
|
||||
tg-show-tools > updated_tools.txt
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- [`tg-show-config`](tg-show-config.md) - Show TrustGraph configuration
|
||||
- [`tg-show-prompts`](tg-show-prompts.md) - Display available prompts
|
||||
- [`tg-show-flows`](tg-show-flows.md) - Show active flows
|
||||
- [`tg-invoke-agent`](tg-invoke-agent.md) - Invoke agent with tools
|
||||
|
||||
## See Also
|
||||
|
||||
- TrustGraph Agent Documentation
|
||||
- Tool Configuration Guide
|
||||
- Agent API Reference
|
||||
Loading…
Add table
Add a link
Reference in a new issue