​
Description

The db command group provides database management and monitoring capabilities for local agent deployments. It includes tools for viewing invocation history, analyzing performance metrics, and maintaining database health.

​
Subcommands

CommandDescription
statusShow database status and agent information
invocationsList agent invocation history
invocationView detailed invocation information
cleanupClean up old database records

​
runagent db status

Shows comprehensive database status including agent capacity, invocation statistics, and recent activity.

​
Options

OptionDescriptionDefault
--agent-idShow details for specific agentNone
--capacityShow detailed capacity informationfalse
--cleanup-daysClean up records older than N daysNone

​
Examples

# Show general database status
runagent db status

# Show capacity management details
runagent db status --capacity

# Show agent-specific information
runagent db status --agent-id abc123def456

​
runagent db invocations

Lists agent invocation history with filtering and formatting options.

​
Options

OptionDescriptionDefault
--agent-idFilter by specific agentNone
--statusFilter by status (pending/completed/failed)None
--limitMaximum number of results20
--formatOutput format (table/json)table

​
Examples

# Show recent invocations
runagent db invocations

# Filter by agent and status
runagent db invocations --agent-id abc123 --status completed

# Get JSON output for analysis
runagent db invocations --format json --limit 50

​
runagent db invocation

Displays detailed information about a specific invocation including input/output data, timing, and error details.

​
Arguments

ArgumentDescriptionRequired
invocation_idFull or partial invocation IDYes

​
Options

OptionDescriptionDefault
--formatOutput format (table/json)table

​
Examples

# View invocation details
runagent db invocation bb3c7a39-c582-4243-a913

# Get JSON output
runagent db invocation bb3c7a39 --format json

​
runagent db cleanup

Removes old database records to maintain performance and reduce storage usage.

​
Options

OptionDescriptionDefault
--daysRemove records older than N days30
--agent-runsAlso clean old agent_runs tablefalse
--yesSkip confirmation promptfalse

​
Examples

# Clean up records older than 30 days
runagent db cleanup

# Clean up records older than 7 days
runagent db cleanup --days 7

# Clean up with no confirmation
runagent db cleanup --days 14 --yes

​
Common Use Cases

​
Monitor Agent Performance

# Check overall health
runagent db status

# View recent activity
runagent db invocations --limit 10

# Check for errors
runagent db invocations --status failed

​
Debug Failed Invocations

# Find failed invocations
runagent db invocations --status failed

# Get detailed error information
runagent db invocation <failed_invocation_id>

​
Analyze Agent Usage

# View agent-specific metrics
runagent db status --agent-id your_agent_id

# Export data for analysis
runagent db invocations --format json > invocations.json

​
Database Maintenance

# Check capacity status
runagent db status --capacity

# Clean up old records
runagent db cleanup --days 30 --agent-runs

​
Database Schema

The database tracks the following key information:
  • Agents: Deployed agent metadata and statistics
  • Invocations: Detailed execution records with timing and I/O data
  • Agent Runs: Legacy execution tracking (maintained for compatibility)
Each invocation includes:
  • Unique invocation ID
  • Input/output data
  • Execution timing
  • Error details (if failed)
  • SDK type and client information

​
Notes

  • All timestamps are in ISO format
  • JSON output can be piped to files for further analysis
  • Cleanup operations are irreversible - use with caution
  • Database is automatically created when first agent is deployed