standard-out-setup（标准输出设置）

Standard Out Setup

Guide for adding console output to make errors visible to agents. This is one of the most critical leverage points - without stdout visibility, agents operate blind.

When to Use

• Agent failures with no visible error output
• Silent functions that return without logging
• New codebase setup for agentic coding
• Debugging why agents can't self-correct

Why Standard Out Matters

Agents can only act on what they can see. If your application fails silently:

• Agent doesn't know something went wrong
• Agent can't identify the error
• Agent can't fix the issue
• Human intervention required (breaks autonomy)

Standard out is often the missing link when agents fail.

The Pattern

Before (Agent Can't See)

def process_data(data):
    return transform(data)  # Silent - what happened?

function processData(data) {
    return transform(data);  // Silent - success? failure?
}

After (Agent Can See)

def process_data(data):
    try:
        result = transform(data)
        print(f"SUCCESS: Processed {len(result)} items")
        return result
    except Exception as e:
        print(f"ERROR in process_data: {str(e)}")
        raise

function processData(data) {
    try {
        const result = transform(data);
        console.log(`SUCCESS: Processed ${result.length} items`);
        return result;
    } catch (error) {
        console.error(`ERROR in processData: ${error.message}`);
        throw error;
    }
}

What to Log

Always Log

1. Success with context

- What operation completed - How many items processed - What was created/modified

1. Errors with detail

- What operation failed - The error message - Enough context to debug

1. State changes

- Files created/modified/deleted - API calls made - Database operations

Don't Over-Log

• Avoid logging every loop iteration
• Don't log sensitive data (passwords, tokens)
• Keep messages concise but informative

Implementation Workflow

Step 1: Identify Key Functions

Look for:

• API endpoints
• Data processing functions
• File operations
• External service calls
• Database operations

Step 2: Add Success Logging

For each function, add output on success:

print(f"SUCCESS: {operation} completed - {context}")

Step 3: Add Error Logging

Wrap in try/except with error output:

try:
    # operation
except Exception as e:
    print(f"ERROR in {function_name}: {str(e)}")
    raise  # Re-raise so agent sees the error

Step 4: Verify Visibility

Run the application and verify:

• Can you see success messages?
• Can you see error messages when things fail?
• Is there enough context to understand what happened?

Language-Specific Patterns

Python

import logging

# Simple print for immediate visibility
print(f"INFO: Starting {operation}")
print(f"SUCCESS: {operation} complete")
print(f"ERROR: {operation} failed - {error}")

# Or use logging for more control
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

logger.info(f"Starting {operation}")
logger.error(f"{operation} failed: {error}")

TypeScript/JavaScript

// Simple console for immediate visibility
console.log(`INFO: Starting ${operation}`);
console.log(`SUCCESS: ${operation} complete`);
console.error(`ERROR: ${operation} failed - ${error.message}`);

// Or use a logger
import { logger } from './logger';

logger.info(`Starting ${operation}`);
logger.error(`${operation} failed`, { error });

Go

import "log"

log.Printf("INFO: Starting %s", operation)
log.Printf("SUCCESS: %s complete", operation)
log.Printf("ERROR: %s failed - %v", operation, err)

API Endpoint Pattern

This is the most common place agents need visibility:

@app.post("/api/upload")
async def upload_file(file: UploadFile):
    print(f"INFO: Received upload request for {file.filename}")
    try:
        result = await process_file(file)
        print(f"SUCCESS: Uploaded {file.filename} - {len(result)} rows processed")
        return {"status": "success", "rows": len(result)}
    except Exception as e:
        print(f"ERROR: Upload failed for {file.filename} - {str(e)}")
        raise HTTPException(status_code=500, detail=str(e))

Anti-Patterns to Fix

Silent Returns

# BAD
def fetch_data():
    return requests.get(url).json()

# GOOD
def fetch_data():
    print(f"INFO: Fetching data from {url}")
    response = requests.get(url)
    print(f"SUCCESS: Received {len(response.content)} bytes")
    return response.json()

Bare Except Blocks

# BAD - agent never sees the error
try:
    risky_operation()
except:
    pass

# GOOD - agent sees what went wrong
try:
    risky_operation()
except Exception as e:
    print(f"ERROR: risky_operation failed - {str(e)}")
    raise

Empty Catch Blocks

// BAD
try {
    riskyOperation();
} catch (e) {}

// GOOD
try {
    riskyOperation();
} catch (error) {
    console.error(`ERROR: riskyOperation failed - ${error.message}`);
    throw error;
}

Verification Checklist

After adding stdout:

• Success messages appear for normal operations
• Error messages appear when operations fail
• Messages include enough context to understand what happened
• Agent can see and react to the output
• Sensitive data is not logged

Related Memory Files

• @12-leverage-points.md - Standard out is leverage point #5
• @agent-perspective-checklist.md - Visibility checklist
• @agentic-kpis.md - Measure improvement

Version History

• v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101