Agentuity Docs

SSH into containers, inspect sessions, and troubleshoot issues in your deployed agents.

Debug live deployments by SSHing into containers, transferring files, inspecting sessions and threads, and viewing deployment logs.

SSH Access

Connect to your deployed containers for debugging:

# SSH into current project
agentuity cloud ssh
 
# SSH into specific project
agentuity cloud ssh proj_abc123xyz
 
# SSH into specific deployment
agentuity cloud ssh dep_abc123xyz
 
# Run a command and exit
agentuity cloud ssh 'ps aux'
 
# Run command on specific project
agentuity cloud ssh proj_abc123xyz 'tail -f /var/log/app.log'
 
# Show SSH command without executing
agentuity cloud ssh --show

SSH Key Required

Add your SSH public key before connecting:

agentuity auth ssh add ~/.ssh/id_rsa.pub

See Getting Started for authentication setup.

Interactive session:

agentuity cloud ssh
 
# Now you're in the container
cd /app
ls -la
cat .env
exit

File Transfer

Use SCP to upload and download files from deployments:

# Upload file to home directory
agentuity cloud scp upload ./config.json
 
# Upload to specific path
agentuity cloud scp upload ./config.json /app/config.json
 
# Upload to specific project
agentuity cloud scp upload ./config.json --identifier=proj_abc123xyz
 
# Upload multiple files
agentuity cloud scp upload ./logs/*.log ~/logs/
 
# Download file to current directory
agentuity cloud scp download /var/log/app.log
 
# Download to specific path
agentuity cloud scp download /var/log/app.log ./logs/
 
# Download from specific project
agentuity cloud scp download /app/config.json --identifier=proj_abc123xyz
 
# Download multiple files
agentuity cloud scp download ~/logs/*.log ./logs/

Common use cases:

Upload configuration files for testing
Download logs for local analysis
Transfer debug scripts
Backup application state

Agent Inspection

List and inspect agents deployed in your project:

# List all agents in the project
agentuity cloud agent list
 
# List agents for a specific project
agentuity cloud agent list --project-id=proj_abc123xyz
 
# Get details for a specific agent
agentuity cloud agent get agent_abc123xyz
 
# View agent input/output schema
agentuity cloud agent schema agent_abc123xyz

Agent details include:

Agent ID and name
Description and metadata
Associated routes
Schema definitions (input/output types)

Use agent inspection to:

Verify deployed agent configuration
Debug schema mismatches
Explore available agents in a project
Generate client code from schemas

Session Logs

Inspect individual agent sessions, including request details, timeline, and logs:

# List recent sessions
agentuity cloud session list
 
# List 25 most recent sessions
agentuity cloud session list --count=25
 
# Filter by project
agentuity cloud session list --project-id=proj_abc123xyz
 
# Filter by deployment
agentuity cloud session list --deployment-id=dep_abc123xyz
 
# Only successful sessions
agentuity cloud session list --success=true
 
# Only failed sessions
agentuity cloud session list --success=false
 
# Filter by specific trigger type
agentuity cloud session list --trigger=api
 
# Filter by specific environment
agentuity cloud session list --env=production

Get session details:

# Full session information with timeline
agentuity cloud session get sess_abc123xyz

This shows:

Request method, URL, and headers
Success/failure status and error messages
Duration and timing information
Agent execution timeline
Eval runs (if configured)

View session logs:

# View logs for specific session
agentuity cloud session logs sess_abc123xyz
 
# Hide timestamps
agentuity cloud session logs sess_abc123xyz --no-timestamps

Session vs. Deployment Logs

Session logs show output for a single request. Deployment logs show all output from a deployment, including startup, errors, and background tasks.

Thread Inspection

List and manage conversation threads. For details on how threads work in agents, see State Management.

# List recent threads
agentuity cloud thread list
 
# List 25 most recent threads
agentuity cloud thread list --count=25
 
# Filter by project
agentuity cloud thread list --project-id=proj_abc123xyz
 
# Get thread details
agentuity cloud thread get thrd_abc123xyz
 
# Delete a thread
agentuity cloud thread delete thrd_abc123xyz

Thread details include:

Thread ID and timestamps
Associated project
User data (metadata)
Deletion status

Use thread inspection to:

Debug conversation state issues
Clean up old threads
Verify thread metadata
Track thread lifecycle

Deployment Logs

Stream logs from a specific deployment:

# View deployment logs
agentuity cloud deployment logs dep_abc123xyz
 
# Limit to 50 log entries
agentuity cloud deployment logs dep_abc123xyz --limit=50
 
# Hide timestamps
agentuity cloud deployment logs dep_abc123xyz --no-timestamps
 
# Specify project explicitly
agentuity cloud deployment logs dep_abc123xyz --project-id=proj_abc123xyz

Log output includes:

Severity levels (INFO, WARN, ERROR)
Timestamps
Log messages
Stack traces for errors

Use deployment logs to:

Monitor startup issues
Debug background tasks
Track errors across requests
Analyze performance issues

JSON Output for Scripting

All commands support --json for machine-readable output. Combined with jq, you can filter and transform results:

# Get session list as JSON
agentuity --json cloud session list --count=100 > sessions.json
 
# Get thread details as JSON
agentuity --json cloud thread get thrd_abc123xyz
 
# Process with jq
agentuity --json cloud session list | jq '.[] | select(.success == false)'
 
# Find failed sessions in last hour
agentuity --json cloud session list --count=100 | \
  jq '.[] | select(.success == false) | {id, url, error}'
 
# Count sessions by trigger type
agentuity --json cloud session list --count=100 | \
  jq 'group_by(.trigger) | map({trigger: .[0].trigger, count: length})'

Scripting examples:

Here are some practical scripts for monitoring and automation:

#!/bin/bash
# Monitor for failures and send alerts
 
FAILED=$(agentuity --json cloud session list --success=false --count=10)
COUNT=$(echo "$FAILED" | jq 'length')
 
if [ "$COUNT" -gt 5 ]; then
  echo "Alert: $COUNT failed sessions detected"
  echo "$FAILED" | jq '.[] | {id, url, error}'
fi

#!/bin/bash
# Export thread user data
 
agentuity --json cloud thread list --count=100 | \
  jq -r '.[] | [.id, .user_data] | @csv' > threads.csv

Next Steps

Managing Cloud Data: Inspect storage, env vars, and secrets
Deploying to the Cloud: Deploy and manage projects
Logging: Configure logging in your agents

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Debugging Deployments