console-agent

Build AI agents with console.agent() - the jQuery of AI Agents. Drop console.agent(...) anywhere in your code for agentic workflows with the simplicity of console.log(). Use when adding AI agent capabilities, debugging with AI, security auditing, intelligent logging, or runtime analysis.

# 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.20",
  null,
  { 
    tools: ['google_search'],
    persona: 'security'
  }
);
console.log(research.summary);
```

---

## Advanced Features

### Structured Output with Z