Logging System

AgentKit CLI comes with a flexible built-in logging system to help you understand command execution, debug issues, and track runtime status.

Default Behavior

AgentKit defaults to the following:

✅ Console output: Disabled (no logs displayed)
✅ File logging: Disabled (no logs recorded)
💡 Enable on demand: Turn logging on via environment variables as needed

bash

# By default, commands run with no log output
agentkit status

# If you need logs, enable them via environment variables (see below)

Log example:

[2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Loading configuration...
[2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Using launch_type: cloud
[2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Querying status with cloud strategy...
[2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Status query completed: running

Quick Start

Enable File Logging

If you want to save logs to a file:

bash

# Enable file logging (default INFO level)
export AGENTKIT_FILE_ENABLED=true

# Run a command
agentkit deploy

# View the generated log file
cat .agentkit/logs/agentkit-$(date +%Y%m%d).log

Enable Console Logging

If you want to view logs in real time in the console:

bash

# Enable console logging
export AGENTKIT_LOG_CONSOLE=true

# Run a command; now you can see logs in the console
agentkit status

Enable Both Console and File Logging

bash

# Enable both console and file logging
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true

# Run a command
agentkit build

Debug Mode

When you need detailed logs to investigate an issue:

bash

# Enable DEBUG-level logging (enable console and file output)
export AGENTKIT_LOG_LEVEL=DEBUG
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true

# Run a command to view detailed debug information
agentkit build

Environment Variable Configuration

With environment variables, you can fully customize logging behavior.

Basic Configuration

Environment Variable	Description	Default	Example
`AGENTKIT_LOG_CONSOLE`	Whether to display logs in the console	`false`	`true` / `false`
`AGENTKIT_FILE_ENABLED`	Whether to save logs to a file	`false`	`true` / `false`
`AGENTKIT_LOG_LEVEL`	Log level (console and file)	`INFO`	`DEBUG` / `INFO` / `WARNING` / `ERROR`
`AGENTKIT_LOG_FILE`	Log file path (takes effect when file logging is enabled)	`.agentkit/logs/agentkit-YYYYMMDD.log`	`/tmp/my-agent.log`

Advanced Configuration

Control log levels for console and file separately:

Environment Variable	Description	Default
`AGENTKIT_CONSOLE_LOG_LEVEL`	Console log level	`INFO`
`AGENTKIT_FILE_LOG_LEVEL`	File log level	`INFO`

Example:

bash

# Show only important errors in the console, but record everything to a file
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_CONSOLE_LOG_LEVEL=ERROR
export AGENTKIT_FILE_LOG_LEVEL=DEBUG

agentkit launch

Log Levels

AgentKit supports 5 log levels. The higher the level, the fewer messages you see:

Level	Description	Typical Use Cases
`DEBUG`	Detailed debugging information	Troubleshooting, development/debugging
`INFO`	General operational information (default)	Understanding command execution flow
`WARNING`	Warning messages	Tracking potential issues
`ERROR`	Error messages	Focusing on failed operations
`CRITICAL`	Critical errors	Seeing only fatal failures

Common Scenarios

Scenario 1: Normal Use (Default Configuration)

Suitable for day-to-day use: no log output to protect sensitive information.

bash

# No configuration needed; just use it
agentkit status
agentkit deploy

Effect:

✅ Console: clean and tidy, no log output
✅ Files: no log files generated, protecting sensitive information

Scenario 1.1: Need to Save Log Records

Enable file logging to help trace operational history:

bash

# Enable file logging
export AGENTKIT_FILE_ENABLED=true

# Run a command
agentkit deploy

Effect:

✅ Console: clean and tidy
✅ Logs: automatically saved to .agentkit/logs/ at INFO level by default

Scenario 2: Debugging Issues

When encountering errors or abnormal behavior, enable detailed logs:

bash

# Enable DEBUG logs for both console and file
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_LOG_LEVEL=DEBUG

# Run a command
agentkit build

Effect:

✅ Console: shows detailed execution steps
✅ Log file: records full DEBUG details for post-incident analysis

Scenario 3: CI/CD Environment

In CI, you typically want logs in the console and also keep a full record:

bash

# Set in your CI configuration file
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_CONSOLE_LOG_LEVEL=INFO
export AGENTKIT_FILE_LOG_LEVEL=DEBUG
export AGENTKIT_LOG_FILE=/var/log/agentkit/build-${BUILD_ID}.log

# Run the build
agentkit launch

Effect:

✅ Console: shows key information for CI log review
✅ Log file: keeps detailed information for later analysis

Scenario 4: Production Environment

In production, record only warnings and errors to a file:

bash

export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_FILE_LOG_LEVEL=WARNING
export AGENTKIT_LOG_FILE=/var/log/agentkit/production.log

# Run a command
agentkit deploy

Effect:

✅ Console: no output, stays clean
✅ Log file: records only warnings and errors, focusing on issues

Scenario 5: Fully Silent

When you don’t need any logs (default behavior):

bash

# Default configuration is fully silent; no environment variables needed
agentkit status

# Or set explicitly (to ensure previous env vars do not affect)
unset AGENTKIT_LOG_CONSOLE
unset AGENTKIT_FILE_ENABLED

Effect:

✅ Console: no log output
✅ Files: no log files generated

Log File Management

Log File Location

When file logging is enabled (AGENTKIT_FILE_ENABLED=true), logs are stored under .agentkit/logs/ in the project root:

your-project/
├── .agentkit/
│   └── logs/
│       ├── agentkit-20251120.log  # Today's logs
│       ├── agentkit-20251119.log  # Yesterday's logs
│       └── agentkit-20251118.log  # The day before yesterday's logs
├── agentkit.yaml
└── my_agent.py

Automatic Cleanup of Old Logs

Log files accumulate over time; it’s recommended to clean them up periodically:

bash

# Delete logs older than 7 days
find .agentkit/logs -name "agentkit-*.log" -mtime +7 -delete

# Or delete manually
rm .agentkit/logs/agentkit-20251101.log

Custom Log Path

bash

# Save to a specific location
export AGENTKIT_LOG_FILE=/tmp/my-custom-agent.log

# Or save to a user directory
export AGENTKIT_LOG_FILE=$HOME/.agentkit-logs/agent.log

agentkit deploy

Configuration Precedence

When multiple configuration methods are present, the precedence is (high to low):

Dedicated environment variables - AGENTKIT_CONSOLE_LOG_LEVEL
General environment variables - AGENTKIT_LOG_LEVEL
Default value - INFO

Example:

bash

# Set the general level to INFO
export AGENTKIT_LOG_LEVEL=INFO

# Set a dedicated console level to WARNING (higher priority)
export AGENTKIT_CONSOLE_LOG_LEVEL=WARNING

# Result: console shows WARNING, file records INFO
agentkit status

Troubleshooting

No Log File Created

Possible causes:

File logging is disabled
Insufficient directory permissions

How to fix:

bash

# 1. Check whether file logging is disabled
echo $AGENTKIT_FILE_ENABLED  # should be true or empty

# 2. Check directory permissions
ls -la .agentkit/logs/

# 3. Create the directory manually
mkdir -p .agentkit/logs

# 4. Ensure environment variables are correct
unset AGENTKIT_FILE_ENABLED  # reset to default

No Console Log Output

Possible causes:

Console logging is disabled by default
Log level is set too high

How to fix:

bash

# 1. Enable console logging
export AGENTKIT_LOG_CONSOLE=true

# 2. Set an appropriate log level
export AGENTKIT_CONSOLE_LOG_LEVEL=INFO

# 3. Run a command
agentkit status

Too Many or Too Few Logs

Adjust the log level:

bash

# Too many logs - show only important information
export AGENTKIT_LOG_LEVEL=WARNING

# Too few logs - view detailed information
export AGENTKIT_LOG_LEVEL=DEBUG

Best Practices

Recommended Development Configuration

Optionally add to your .bashrc or .zshrc:

bash

# AgentKit development environment configuration (choose as needed)
# Option 1: Enable console logs only
export AGENTKIT_LOG_CONSOLE=true

# Option 2: Enable both console and file logs
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_CONSOLE_LOG_LEVEL=INFO
export AGENTKIT_FILE_LOG_LEVEL=DEBUG

Recommendations:

Keep it unconfigured by default to stay clean
Enable temporarily when debugging
Avoid accidentally recording sensitive information

Team Collaboration

Create a .env.example file in the project root:

bash

# AgentKit logging configuration example
# Copy to .env and modify as needed

# === Recommended dev configuration ===
# Enable console logs (for real-time viewing)
AGENTKIT_LOG_CONSOLE=true

# Enable file logging (optional; useful for tracing issues)
# AGENTKIT_FILE_ENABLED=true

# Set log level
AGENTKIT_LOG_LEVEL=INFO

# Custom log path (optional)
# AGENTKIT_LOG_FILE=./logs/my-agent.log

Reminder:

Team members should adjust based on their needs
.env should be in .gitignore to avoid committing personal configuration
Keep file logging disabled by default to protect sensitive information

Production Deployment Recommendations

bash

# Production configuration
export AGENTKIT_LOG_CONSOLE=false          # Disable console
export AGENTKIT_FILE_ENABLED=true          # Enable file logging
export AGENTKIT_FILE_LOG_LEVEL=WARNING     # Record warnings and errors only
export AGENTKIT_LOG_FILE=/var/log/agentkit/prod.log  # Unified path

Benefits:

Reduces unnecessary output
Focuses on important issues
Easier log management and monitoring

Summary

AgentKit logging system design principles:

🔒 Security first - no logs by default to avoid information leaks
🎯 Enable on demand - turn on via environment variables when needed
🔧 Flexible configuration - control console and file independently
📊 Level-based control - use different log levels for different scenarios
📁 Automatic management - split by date for easier lookup once enabled

Quick reference:

bash

# 1. Enable file logging
export AGENTKIT_FILE_ENABLED=true

# 2. Enable console debugging
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_LOG_LEVEL=DEBUG

# 3. View log file (file logging must be enabled first)
cat .agentkit/logs/agentkit-$(date +%Y%m%d).log

# 4. Use different levels for console and file
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_FILE_ENABLED=true
export AGENTKIT_CONSOLE_LOG_LEVEL=ERROR
export AGENTKIT_FILE_LOG_LEVEL=DEBUG

If you run into issues, refer to the Troubleshooting section or contact technical support.

Logging System ​

Default Behavior ​

Quick Start ​

Enable File Logging ​

Enable Console Logging ​

Enable Both Console and File Logging ​

Debug Mode ​

Environment Variable Configuration ​

Basic Configuration ​

Advanced Configuration ​

Log Levels ​

Common Scenarios ​

Scenario 1: Normal Use (Default Configuration) ​

Scenario 1.1: Need to Save Log Records ​

Scenario 2: Debugging Issues ​

Scenario 3: CI/CD Environment ​

Scenario 4: Production Environment ​

Scenario 5: Fully Silent ​

Log File Management ​

Log File Location ​

Automatic Cleanup of Old Logs ​

Custom Log Path ​

Configuration Precedence ​

Troubleshooting ​

No Log File Created ​

No Console Log Output ​

Too Many or Too Few Logs ​

Best Practices ​

Recommended Development Configuration ​

Team Collaboration ​

Production Deployment Recommendations ​

Summary ​

Logging System

Default Behavior

Quick Start

Enable File Logging

Enable Console Logging

Enable Both Console and File Logging

Debug Mode

Environment Variable Configuration

Basic Configuration

Advanced Configuration

Log Levels

Common Scenarios

Scenario 1: Normal Use (Default Configuration)

Scenario 1.1: Need to Save Log Records

Scenario 2: Debugging Issues

Scenario 3: CI/CD Environment

Scenario 4: Production Environment

Scenario 5: Fully Silent

Log File Management

Log File Location

Automatic Cleanup of Old Logs

Custom Log Path

Configuration Precedence

Troubleshooting

No Log File Created

No Console Log Output

Too Many or Too Few Logs

Best Practices

Recommended Development Configuration

Team Collaboration

Production Deployment Recommendations

Summary