console-agent

使用 console.agent() 构建 AI 代理 - AI 代理的 jQuery。将 console.agent(...) 放在代码中的任何位置，以使用 console.log() 的简单性实现代理工作流程。在添加 AI 代理功能、使用 AI 进行调试、安全审核、智能日志记录或运行时分析时使用。

## 概述（中文）

使用 console.agent() 构建 AI 代理 - AI 代理的 jQuery。将 console.agent(...) 放在代码中的任何位置，以使用 console.log() 的简单性实现代理工作流程。在添加 AI 代理功能、使用 AI 进行调试、安全审核、智能日志记录或运行时分析时使用。

## 原文

# console.agent - The jQuery of AI Agents

Comprehensive guide for implementing `@console-agent/agent` — drop `console.agent(...)` anywhere in your code to execute agentic workflows with the simplicity of `console.log()`.

**Official Documentation:** https://console-agent.github.io  
**Package:** `@console-agent/agent` (npm) / `console-agent` (PyPI)  
**Version:** v1.2.0  
**Provider:** Google Gemini (gemini-2.5-flash-lite, gemini-3-flash-preview)

## When to Apply

Reference this skill when:
- User wants to add AI agent capabilities to their code
- User asks about debugging with AI assistance
- User mentions "console.agent" or agentic workflows
- User wants runtime analysis, security audits, or code review
- User needs intelligent logging, testing assistance, or data validation
- User asks about tools like code execution, Google Search, or file analysis

## Core Concepts

### 1. Fire-and-Forget by Default (Non-blocking)
```javascript
// Returns immediately, agent runs async in background
console.agent("analyze this error", error);
// Code continues executing...
```

### 2. Blocking Mode (Await for Structured Results)
```javascript
// Wait for complete AgentResult
const result = await console.agent("validate email", email);
if (!result.success) throw new Error(result.summary);
```

### 3. AI Personas (Auto-detected or Explicit)
- **Security** 🛡️ - OWASP expert (detects: injection, xss, vulnerability, csrf)
- **Debugger** 🐛 - Senior debugging expert (detects: slow, error, optimize, crash)
- **Architect** 🏗️ - Principal engineer (detects: design, architecture, schema)
- **General** 🔍 - Full-stack senior engineer (default fallback)

### 4. Output Modes

**Default (verbose: false):**
```
SQL injection detected in user input
fix: Use parameterized queries
severity: critical
```

**Verbose (verbose: true):**
```
[AGENT] ✓ 🛡️ Security audit Complete
[AGENT] ├─ ✓ SQL injection detected in user input
[AGENT] ├─ Tool: google_search
[AGENT] ├─ fix: Use parameterized queries
[AGENT] └─ confidence: 0.94 | 247ms | 156 tokens | model: gemini-2.5-flash-lite
```

---

## Installation & Setup

### JavaScript/TypeScript
```bash
npm install @console-agent/agent
```

### Python
```bash
pip install console-agent
```

### Get Free API Key
https://aistudio.google.com/apikey

### Minimal Setup (Zero Config Works!)
```javascript
// Just set environment variable
export GEMINI_API_KEY="your-key-here"

// Import and use
import '@console-agent/agent';
console.agent("analyze this", data);
```

### Optional Configuration
```javascript
import { init } from '@console-agent/agent';

init({
  apiKey: process.env.GEMINI_API_KEY,
  model: 'gemini-2.5-flash-lite',  // Default
  persona: 'general',
  mode: 'fire-and-forget',
  timeout: 10000,
  
  budget: {
    maxCallsPerDay: 100,
    maxTokensPerCall: 8000,
    costCapDaily: 1.00  // USD
  },
  
  anonymize: true,              // Auto-strip secrets/PII
  localOnly: false,             // Disable cloud tools
  includeCallerSource: true,    // Auto-read source file
  logLevel: 'info'
});
```

### Python Configuration
```python
from console_agent import init_agent, agent

init_agent(
    api_key=os.getenv('GEMINI_API_KEY'),
    model='gemini-2.5-flash-lite',
    persona='general',
    budget={'maxCallsPerDay': 100}
)
```

---

## API Reference

### `console.agent(prompt, context?, options?)`
Main API - call it like `console.log()`.

```javascript
// Simple fire-and-forget
console.agent("explain this error", error);

// Await structured results
const result = await console.agent("analyze", data, {
  persona: 'security',
  model: 'gemini-3-flash-preview',
  thinking: { level: 'high', includeThoughts: true },
  tools: ['google_search', 'code_execution']
});
```

### Return Type: `AgentResult`
```typescript
interface AgentResult {
  success: boolean;           // Overall task success
  summary: string;            // Human-readable conclusion
  reasoning?: string;         // Agent's thought process (if thinking enabled)
  data: Record<string, any>;  // Structured findings
  actions: string[];          // Tools used / steps taken
  confidence: number;         // 0-1 confidence score
  metadata: {
    model: string;
    tokensUsed: number;
    latencyMs: number;
    toolCalls: ToolCall[];
    cached: boolean;
  };
}
```

### Persona Shortcuts
```javascript
// Auto-selects security persona
console.agent.security("audit this query", sql);

// Auto-selects debugger persona
console.agent.debug("why is this slow?", metrics);

// Auto-selects architect persona
console.agent.architect("review API design", endpoint);
```

---

## Built-in Tools

**IMPORTANT:** Tools are opt-in. Only activated when explicitly passed via `tools: [...]`.

### 1. Google Search 🔍
Real-time web grounding - search for current info, CVEs, documentation.

```javascript
const result = await console.agent(
  "What is the current population of Tokyo?",
  null,
  { tools: ['google_search'] }
);
```

### 2. Code Execution 💻
Python sandbox (Gemini-hosted) - calculations, data processing, algorithm verification.

```javascript
const result = await console.agent(
  "Calculate the 20th Fibonacci number",
  null,
  { tools: ['code_execution'] }
);
// result.data.result → 6765
```

### 3. URL Context 🌐
Fetch and analyze web pages - read docs, analyze APIs, extract content.

```javascript
const result = await console.agent(
  "Summarize this page",
  null,
  { tools: ['url_context'] }
);
```

### Combining Multiple Tools
```javascript
// Agent decides which tools to use based on prompt
const result = await console.agent(
  "Search for current world population, then calculate 1% of it",
  null,
  { tools: ['google_search', 'code_execution'] }
);
// 1. Uses google_search to find population
// 2. Uses code_execution to calculate 1%
// 3. Returns combined result
```

---

## Common Use Cases

### 1. Security Auditing 🛡️
```javascript
app.post('/api/search', async (req, res) => {
  const query = req.body.q;
  
  const audit = await console.agent.security(
    "check for SQL injection", 
    query
  );
  
  if (audit.data.severity === 'critical') {
    return res.status(400).json({ error: "Invalid input" });
  }
  
  const results = await db.search(query);
  res.json(results);
});
```

### 2. Debugging Failed Tests 🐛
```javascript
import { agent } from '@console-agent/agent';
import { test, expect } from 'vitest';

test('payment processing', async () => {
  const result = await processPayment(order);
  
  if (!result.success) {
    await agent.debug("why did payment fail?", {
      order,
      result,
      testName: 'payment processing'
    });
  }
  
  expect(result.success).toBe(true);
});
```

**Output:**
```
Likely cause: Missing await on async fn
Suggested fix: Add 'await' on line 47
Confidence: 0.92 | 312ms | 189 tokens
```

### 3. Data Validation 📊
```javascript
const records = await fetchBatch();

const validation = await console.agent(
  "validate batch meets schema", 
  records,
  { 
    schema: z.object({
      valid: z.boolean(),
      errors: z.array(z.string()),
      quality_score: z.number()
    })
  }
);

if (!validation.data.valid) {
  console.log("Issues:", validation.data.errors);
}
```

### 4. Architecture Review 🏗️
```javascript
console.agent.architect("review API design", {
  endpoint: '/api/users',
  method: 'POST',
  handler: userController,
  middleware: [auth, rateLimit]
});
```

### 5. Performance Analysis
```javascript
const startTime = Date.now();
const result = await slowOperation();
const duration = Date.now() - startTime;

if (duration > 1000) {
  agent.debug("why is this slow?", {
    operation: 'slowOperation',
    duration,
    input: operationInput
  });
}
```

### 6. Research with Tools 🔍
```javascript
const research = await console.agent(
  "research known CVEs for lodash@4.17