From 9de63c1cef11cc3765f9cd165af07e66c73d7f18 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:27:23 +0000 Subject: [PATCH 1/3] Initial plan From a5ac2ea83d53493aa9b6421ce10aad032199a6a3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:35:49 +0000 Subject: [PATCH 2/3] feat: add developer debug panel with dev mode Co-authored-by: vreshch <9742863+vreshch@users.noreply.github.com> --- .../agent-sdk-devpanel-example/.env.example | 1 + .../agent-sdk-devpanel-example/.gitignore | 4 + examples/agent-sdk-devpanel-example/README.md | 66 +++++++ examples/agent-sdk-devpanel-example/index.ts | 68 +++++++ .../agent-sdk-devpanel-example/package.json | 22 +++ .../agent-sdk-devpanel-example/tsconfig.json | 8 + package-lock.json | 9 - packages/core/src/types/agent.types.ts | 1 + packages/sdk/src/agent.ts | 48 ++++- packages/sdk/src/devpanel.test.ts | 166 ++++++++++++++++++ packages/sdk/src/devpanel.ts | 159 +++++++++++++++++ packages/sdk/src/index.ts | 1 + packages/sdk/tsconfig.json | 30 +--- 13 files changed, 546 insertions(+), 37 deletions(-) create mode 100644 examples/agent-sdk-devpanel-example/.env.example create mode 100644 examples/agent-sdk-devpanel-example/.gitignore create mode 100644 examples/agent-sdk-devpanel-example/README.md create mode 100644 examples/agent-sdk-devpanel-example/index.ts create mode 100644 examples/agent-sdk-devpanel-example/package.json create mode 100644 examples/agent-sdk-devpanel-example/tsconfig.json create mode 100644 packages/sdk/src/devpanel.test.ts create mode 100644 packages/sdk/src/devpanel.ts diff --git a/examples/agent-sdk-devpanel-example/.env.example b/examples/agent-sdk-devpanel-example/.env.example new file mode 100644 index 0000000..f0ac698 --- /dev/null +++ b/examples/agent-sdk-devpanel-example/.env.example @@ -0,0 +1 @@ +OPENAI_API_KEY=your-api-key-here diff --git a/examples/agent-sdk-devpanel-example/.gitignore b/examples/agent-sdk-devpanel-example/.gitignore new file mode 100644 index 0000000..3b24e4a --- /dev/null +++ b/examples/agent-sdk-devpanel-example/.gitignore @@ -0,0 +1,4 @@ +node_modules +dist +.env +*.log diff --git a/examples/agent-sdk-devpanel-example/README.md b/examples/agent-sdk-devpanel-example/README.md new file mode 100644 index 0000000..f1ea53f --- /dev/null +++ b/examples/agent-sdk-devpanel-example/README.md @@ -0,0 +1,66 @@ +# Dev Panel Example + +This example demonstrates how to use the AgentKit Developer Panel for debugging agent execution. + +## Features + +- Initialize and configure the dev panel +- Enable dev mode on agents +- View real-time logging of: + - Agent configuration + - Messages sent/received + - Tool calls and results + - Model responses +- Display a visual summary panel + +## Setup + +1. Copy `.env.example` to `.env`: + ```bash + cp .env.example .env + ``` + +2. Add your OpenAI API key to `.env`: + ```env + OPENAI_API_KEY=sk-your-key-here + ``` + +3. Install dependencies (from the repo root): + ```bash + npm install + ``` + +## Run + +```bash +npm start +``` + +## Dev Mode + +The dev panel is automatically enabled when `NODE_ENV=development` or can be explicitly enabled: + +```typescript +// Explicit initialization +const devPanel = initDevPanel({ + enabled: true, + logLevel: 'verbose', // 'verbose' | 'normal' | 'minimal' + showTimestamps: true, +}); + +// Enable on agent +const agent = agent('my-agent') + .model('gpt-4') + .devMode(true); // Enable dev panel logging for this agent +``` + +## Output + +The dev panel logs: +- šŸ”§ Agent Configuration +- šŸ’¬ Messages +- šŸ”Ø Tool Calls +- āœ… Responses +- āŒ Errors + +And displays a summary panel at the end with all events. diff --git a/examples/agent-sdk-devpanel-example/index.ts b/examples/agent-sdk-devpanel-example/index.ts new file mode 100644 index 0000000..7250f90 --- /dev/null +++ b/examples/agent-sdk-devpanel-example/index.ts @@ -0,0 +1,68 @@ +import { agent, tool, initDevPanel, showDevPanel } from '@agentage/sdk'; +import { z } from 'zod'; +import dotenv from 'dotenv'; + +dotenv.config(); + +async function main(): Promise { + console.log('šŸ¤– AgentKit Dev Panel Example\n'); + + // Initialize the dev panel + const devPanel = initDevPanel({ + enabled: true, + logLevel: 'verbose', + showTimestamps: true, + }); + + console.log('āœ… Dev Panel initialized (enabled: ' + devPanel.isEnabled() + ')\n'); + + // Create a simple tool for demonstration + const weatherTool = tool( + { + name: 'get_weather', + description: 'Get weather information for a location', + inputSchema: { + location: z.string().describe('The city name'), + }, + }, + async ({ location }) => { + return { + location, + temperature: 72, + condition: 'Sunny', + forecast: 'Clear skies expected', + }; + } + ); + + // Create agent with dev mode enabled + const assistant = agent('weather-assistant') + .model('gpt-4', { temperature: 0.7 }) + .config([{ key: 'OPENAI_API_KEY', value: process.env.OPENAI_API_KEY! }]) + .instructions('You are a helpful weather assistant.') + .tools([weatherTool]) + .devMode(true); // Enable dev mode for this agent + + console.log('šŸ’¬ Sending message to Agent...\n'); + + // Send a message that will trigger the tool + try { + const response = await assistant.send('What is the weather in San Francisco?'); + + console.log('\nāœ… Response from Agent:\n'); + console.log(response.content); + console.log('\nšŸ“Š Metadata:', response.metadata); + } catch (error) { + console.error('Error:', error); + } + + // Show the dev panel summary + console.log('\n'); + console.log('ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•'); + console.log(' DEV PANEL SUMMARY '); + console.log('ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•\n'); + + showDevPanel(); +} + +main().catch(console.error); diff --git a/examples/agent-sdk-devpanel-example/package.json b/examples/agent-sdk-devpanel-example/package.json new file mode 100644 index 0000000..1ddb9d9 --- /dev/null +++ b/examples/agent-sdk-devpanel-example/package.json @@ -0,0 +1,22 @@ +{ + "name": "agent-sdk-devpanel-example", + "version": "1.0.0", + "type": "module", + "private": true, + "description": "Example demonstrating AgentKit Dev Panel feature", + "scripts": { + "start": "tsx index.ts", + "dev": "tsx watch index.ts" + }, + "dependencies": { + "@agentage/core": "file:../../packages/core", + "@agentage/sdk": "file:../../packages/sdk", + "dotenv": "^16.4.5", + "zod": "^4.2.1" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "tsx": "^4.6.0", + "typescript": "^5.3.0" + } +} diff --git a/examples/agent-sdk-devpanel-example/tsconfig.json b/examples/agent-sdk-devpanel-example/tsconfig.json new file mode 100644 index 0000000..d954fdb --- /dev/null +++ b/examples/agent-sdk-devpanel-example/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./dist" + }, + "include": ["**/*.ts"], + "exclude": ["node_modules", "dist"] +} diff --git a/package-lock.json b/package-lock.json index 1108736..c59a305 100644 --- a/package-lock.json +++ b/package-lock.json @@ -70,7 +70,6 @@ "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@babel/code-frame": "^7.27.1", "@babel/generator": "^7.28.5", @@ -2299,7 +2298,6 @@ "integrity": "sha512-hM5faZwg7aVNa819m/5r7D0h0c9yC4DUlWAOvHAtISdFTc8xB86VmX5Xqabrama3wIPJ/q9RbGS1worb6JfnMg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.50.1", "@typescript-eslint/types": "8.50.1", @@ -2780,7 +2778,6 @@ "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "dev": true, "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -3067,7 +3064,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "baseline-browser-mapping": "^2.8.19", "caniuse-lite": "^1.0.30001751", @@ -3499,7 +3495,6 @@ "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", @@ -4356,7 +4351,6 @@ "integrity": "sha512-F26gjC0yWN8uAA5m5Ss8ZQf5nDHWGlN/xWZIh8S5SRbsEKBovwZhxGd6LJlbZYxBgCYOtreSUyb8hpXyGC5O4A==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@jest/core": "30.2.0", "@jest/types": "30.2.0", @@ -6531,7 +6525,6 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=12" }, @@ -6708,7 +6701,6 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "dev": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -7036,7 +7028,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-4.2.1.tgz", "integrity": "sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/packages/core/src/types/agent.types.ts b/packages/core/src/types/agent.types.ts index 5f33dc7..ddf3eb5 100644 --- a/packages/core/src/types/agent.types.ts +++ b/packages/core/src/types/agent.types.ts @@ -32,6 +32,7 @@ export interface Agent { toolList: Tool[] ): Agent; config(configEntries: ConfigEntry[]): Agent; + devMode?(enabled?: boolean): Agent; send(message: string): Promise; stream(message: string): AsyncIterableIterator; } diff --git a/packages/sdk/src/agent.ts b/packages/sdk/src/agent.ts index acdc5b3..c454453 100644 --- a/packages/sdk/src/agent.ts +++ b/packages/sdk/src/agent.ts @@ -14,6 +14,7 @@ import { ToolNotFoundError, UnsupportedModelError, } from './errors.js'; +import { getDevPanel } from './devpanel.js'; /** * OpenAI tool definition @@ -99,11 +100,17 @@ class AgentBuilder implements Agent { private _instructions?: string; private _tools?: Tool[]; private _config?: Record; + private _devMode?: boolean; constructor(name: string) { this._name = name; } + devMode(enabled: boolean = true): Agent { + this._devMode = enabled; + return this; + } + model(modelName: string, config?: ModelConfig): Agent { this._modelName = modelName; this._modelConfig = config; @@ -131,6 +138,16 @@ class AgentBuilder implements Agent { } async send(message: string): Promise { + const devPanel = this._devMode ? getDevPanel() : null; + + if (devPanel?.isEnabled()) { + devPanel.log({ + type: 'config', + timestamp: new Date(), + data: this.getConfig(), + }); + } + const modelName = this._modelName || 'gpt-4'; // Only support GPT-4 for now @@ -153,6 +170,14 @@ class AgentBuilder implements Agent { messages.push({ role: 'user', content: message }); + if (devPanel?.isEnabled()) { + devPanel.log({ + type: 'message', + timestamp: new Date(), + data: { role: 'user', content: message }, + }); + } + // Convert tools to OpenAI format const tools = this._tools?.map(convertToOpenAITool); @@ -183,6 +208,17 @@ class AgentBuilder implements Agent { continue; } + if (devPanel?.isEnabled()) { + devPanel.log({ + type: 'tool_call', + timestamp: new Date(), + data: { + name: toolCall.function.name, + arguments: JSON.parse(toolCall.function.arguments), + }, + }); + } + const tool = this._tools?.find( (t) => t.name === toolCall.function.name ); @@ -215,7 +251,7 @@ class AgentBuilder implements Agent { choice = response.choices[0]; } - return { + const agentResponse = { content: choice.message.content || '', metadata: { id: response.id, @@ -224,6 +260,16 @@ class AgentBuilder implements Agent { finishReason: choice.finish_reason, }, }; + + if (devPanel?.isEnabled()) { + devPanel.log({ + type: 'response', + timestamp: new Date(), + data: agentResponse, + }); + } + + return agentResponse; } async *stream(_message: string): AsyncIterableIterator { diff --git a/packages/sdk/src/devpanel.test.ts b/packages/sdk/src/devpanel.test.ts new file mode 100644 index 0000000..d86dd03 --- /dev/null +++ b/packages/sdk/src/devpanel.test.ts @@ -0,0 +1,166 @@ +import { describe, it, expect, beforeEach, afterEach } from '@jest/globals'; +import { + getDevPanel, + initDevPanel, + showDevPanel, + clearDevPanel, +} from './devpanel.js'; + +describe('DevPanel', () => { + let originalEnv: string | undefined; + + beforeEach(() => { + originalEnv = process.env.NODE_ENV; + clearDevPanel(); + }); + + afterEach(() => { + process.env.NODE_ENV = originalEnv; + }); + + describe('initialization', () => { + it('should be disabled by default in non-dev environment', () => { + process.env.NODE_ENV = 'production'; + const panel = initDevPanel(); + expect(panel.isEnabled()).toBe(false); + }); + + it('should be enabled in development environment', () => { + process.env.NODE_ENV = 'development'; + const panel = initDevPanel(); + expect(panel.isEnabled()).toBe(true); + }); + + it('should respect explicit enabled config', () => { + process.env.NODE_ENV = 'production'; + const panel = initDevPanel({ enabled: true }); + expect(panel.isEnabled()).toBe(true); + }); + + it('should respect explicit disabled config', () => { + process.env.NODE_ENV = 'development'; + const panel = initDevPanel({ enabled: false }); + expect(panel.isEnabled()).toBe(false); + }); + }); + + describe('event logging', () => { + it('should log events when enabled', () => { + const panel = initDevPanel({ enabled: true }); + + panel.log({ + type: 'message', + timestamp: new Date(), + data: { test: 'data' }, + }); + + const events = panel.getEvents(); + expect(events).toHaveLength(1); + expect(events[0].type).toBe('message'); + }); + + it('should not log events when disabled', () => { + const panel = initDevPanel({ enabled: false }); + + panel.log({ + type: 'message', + timestamp: new Date(), + data: { test: 'data' }, + }); + + const events = panel.getEvents(); + expect(events).toHaveLength(0); + }); + + it('should track different event types', () => { + const panel = initDevPanel({ enabled: true }); + + const eventTypes: Array<'config' | 'message' | 'tool_call' | 'response' | 'error'> = [ + 'config', + 'message', + 'tool_call', + 'response', + 'error', + ]; + + eventTypes.forEach((type) => { + panel.log({ + type, + timestamp: new Date(), + data: { type }, + }); + }); + + const events = panel.getEvents(); + expect(events).toHaveLength(5); + expect(events.map((e) => e.type)).toEqual(eventTypes); + }); + }); + + describe('event clearing', () => { + it('should clear all logged events', () => { + const panel = initDevPanel({ enabled: true }); + + panel.log({ + type: 'message', + timestamp: new Date(), + data: { test: 'data' }, + }); + + expect(panel.getEvents()).toHaveLength(1); + + panel.clear(); + + expect(panel.getEvents()).toHaveLength(0); + }); + }); + + describe('global instance', () => { + it('should return the same instance', () => { + const panel1 = getDevPanel(); + const panel2 = getDevPanel(); + expect(panel1).toBe(panel2); + }); + + it('should work with global functions', () => { + const panel = initDevPanel({ enabled: true }); + + panel.log({ + type: 'message', + timestamp: new Date(), + data: { test: 'data' }, + }); + + expect(getDevPanel().getEvents()).toHaveLength(1); + + clearDevPanel(); + + expect(getDevPanel().getEvents()).toHaveLength(0); + }); + }); + + describe('show panel', () => { + it('should not throw when showing panel', () => { + const panel = initDevPanel({ enabled: true }); + + panel.log({ + type: 'message', + timestamp: new Date(), + data: { test: 'data' }, + }); + + expect(() => panel.show()).not.toThrow(); + expect(() => showDevPanel()).not.toThrow(); + }); + + it('should handle empty events', () => { + const panel = initDevPanel({ enabled: true }); + expect(() => panel.show()).not.toThrow(); + }); + + it('should show message when disabled', () => { + const panel = initDevPanel({ enabled: false }); + expect(() => panel.show()).not.toThrow(); + }); + }); +}); diff --git a/packages/sdk/src/devpanel.ts b/packages/sdk/src/devpanel.ts new file mode 100644 index 0000000..45ea795 --- /dev/null +++ b/packages/sdk/src/devpanel.ts @@ -0,0 +1,159 @@ +/** + * Developer debug panel for inspecting agent execution + * Only active when NODE_ENV=development or explicitly enabled + */ + +export interface DevPanelConfig { + enabled?: boolean; + logLevel?: 'verbose' | 'normal' | 'minimal'; + showTimestamps?: boolean; +} + +export interface DevPanelEvent { + type: 'config' | 'message' | 'tool_call' | 'response' | 'error'; + timestamp: Date; + data: unknown; +} + +class DevPanel { + private enabled: boolean; + private logLevel: 'verbose' | 'normal' | 'minimal'; + private showTimestamps: boolean; + private events: DevPanelEvent[] = []; + + constructor(config?: DevPanelConfig) { + this.enabled = + config?.enabled !== undefined + ? config.enabled + : process.env.NODE_ENV === 'development'; + this.logLevel = config?.logLevel ?? 'normal'; + this.showTimestamps = config?.showTimestamps ?? true; + } + + log(event: DevPanelEvent): void { + if (!this.enabled) return; + + this.events.push(event); + + const prefix = this.showTimestamps + ? `[${event.timestamp.toISOString()}] ` + : ''; + + switch (event.type) { + case 'config': + if (this.logLevel !== 'minimal') { + console.log(`${prefix}šŸ”§ Agent Configuration:`, event.data); + } + break; + case 'message': + console.log(`${prefix}šŸ’¬ Message:`, event.data); + break; + case 'tool_call': + console.log(`${prefix}šŸ”Ø Tool Call:`, event.data); + break; + case 'response': + console.log(`${prefix}āœ… Response:`, event.data); + break; + case 'error': + console.error(`${prefix}āŒ Error:`, event.data); + break; + } + } + + getEvents(): DevPanelEvent[] { + return [...this.events]; + } + + clear(): void { + this.events = []; + } + + isEnabled(): boolean { + return this.enabled; + } + + /** + * Show a visual panel with all logged events + */ + show(): void { + if (!this.enabled) { + console.log('āŒ Dev Panel is not enabled'); + return; + } + + console.log('\nā•”ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•—'); + console.log('ā•‘ AgentKit Developer Panel ā•‘'); + console.log('ā•šā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•\n'); + + if (this.events.length === 0) { + console.log(' No events logged yet.\n'); + return; + } + + console.log(` Total Events: ${this.events.length}\n`); + + this.events.forEach((event, index) => { + const time = this.showTimestamps + ? event.timestamp.toLocaleTimeString() + : `#${index + 1}`; + console.log(` [${time}] ${this.getEventIcon(event.type)} ${event.type}`); + + if (this.logLevel === 'verbose') { + console.log(' Data:', JSON.stringify(event.data, null, 2)); + } + }); + + console.log('\nā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•\n'); + } + + private getEventIcon(type: DevPanelEvent['type']): string { + switch (type) { + case 'config': + return 'šŸ”§'; + case 'message': + return 'šŸ’¬'; + case 'tool_call': + return 'šŸ”Ø'; + case 'response': + return 'āœ…'; + case 'error': + return 'āŒ'; + default: + return 'šŸ“‹'; + } + } +} + +let globalDevPanel: DevPanel | null = null; + +/** + * Initialize the global dev panel + */ +export function initDevPanel(config?: DevPanelConfig): DevPanel { + globalDevPanel = new DevPanel(config); + return globalDevPanel; +} + +/** + * Get the global dev panel instance + */ +export function getDevPanel(): DevPanel { + if (!globalDevPanel) { + globalDevPanel = new DevPanel(); + } + return globalDevPanel; +} + +/** + * Show the dev panel + */ +export function showDevPanel(): void { + getDevPanel().show(); +} + +/** + * Clear the dev panel + */ +export function clearDevPanel(): void { + getDevPanel().clear(); +} diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts index d9f355a..58fbe86 100644 --- a/packages/sdk/src/index.ts +++ b/packages/sdk/src/index.ts @@ -2,5 +2,6 @@ export * from '@agentage/core'; export * from './agent.js'; export * from './errors.js'; export * from './tool.js'; +export * from './devpanel.js'; export const version = '0.0.1'; diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json index 884f4c6..8b411f1 100644 --- a/packages/sdk/tsconfig.json +++ b/packages/sdk/tsconfig.json @@ -1,33 +1,9 @@ { + "extends": "../../tsconfig.json", "compilerOptions": { - "target": "ES2022", - "module": "ESNext", - "lib": ["ES2022"], - "moduleResolution": "bundler", - "resolveJsonModule": true, - "allowJs": false, "outDir": "./dist", - "rootDir": "./src", - "removeComments": true, - "strict": true, - "noImplicitAny": true, - "strictNullChecks": true, - "strictFunctionTypes": true, - "strictBindCallApply": true, - "strictPropertyInitialization": true, - "noImplicitThis": true, - "alwaysStrict": true, - "noUnusedLocals": true, - "noUnusedParameters": true, - "noImplicitReturns": true, - "noFallthroughCasesInSwitch": true, - "esModuleInterop": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true, - "declaration": true, - "declarationMap": true, - "sourceMap": true + "rootDir": "./src" }, "include": ["src/**/*"], - "exclude": ["node_modules", "dist"] + "exclude": ["node_modules", "dist", "**/*.test.ts"] } From a60e7a6d0e0f3ca8ac362ce1f670968a06353c36 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:38:16 +0000 Subject: [PATCH 3/3] docs: add dev panel documentation and update README Co-authored-by: vreshch <9742863+vreshch@users.noreply.github.com> --- README.md | 32 ++++ docs/dev-panel.md | 363 +++++++++++++++++++++++++++++++++++++ packages/sdk/tsconfig.json | 2 +- 3 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 docs/dev-panel.md diff --git a/README.md b/README.md index d97aefc..d26e922 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ npm install @agentage/sdk - **Type-safe tools** - Zod-based schema validation - **Multiple models** - Support for OpenAI, Anthropic, and custom adapters - **Zero configuration** - Start building agents immediately +- **Developer Debug Panel** - Built-in debugging tools for inspecting agent execution ## Quick Start @@ -199,6 +200,37 @@ const analyst = agent('analyst') .instructions('Provide precise, factual analysis'); ``` +### 6. Developer Debug Panel + +Debug and inspect agent execution in real-time: + +```typescript +import { agent, initDevPanel, showDevPanel } from '@agentage/sdk'; + +// Initialize dev panel (auto-enabled in NODE_ENV=development) +initDevPanel({ enabled: true, logLevel: 'verbose' }); + +// Enable dev mode on agent +const debugAgent = agent('debug-bot') + .model('gpt-4') + .instructions('You are helpful') + .devMode(true); // Enable debug logging + +await debugAgent.send('Hello!'); + +// Show visual dev panel with all events +showDevPanel(); +``` + +The dev panel logs: +- šŸ”§ Agent configuration +- šŸ’¬ Messages sent/received +- šŸ”Ø Tool calls +- āœ… Model responses +- āŒ Errors + +See [Dev Panel Documentation](./docs/dev-panel.md) for complete guide. + ## Philosophy The AgentKit philosophy is to provide small, functional tooling for building AI agents, making it a great solution for chatbots, automation, data processing, or AI-powered applications. diff --git a/docs/dev-panel.md b/docs/dev-panel.md new file mode 100644 index 0000000..0b42c02 --- /dev/null +++ b/docs/dev-panel.md @@ -0,0 +1,363 @@ +# Developer Debug Panel + +The Developer Debug Panel is a debugging utility for AgentKit that helps you inspect and debug agent execution in real-time. It's designed to be used during development to understand how your agents are working. + +## Features + +- šŸ”§ **Agent Configuration Logging**: View agent setup and configuration +- šŸ’¬ **Message Tracking**: See all messages sent to and from agents +- šŸ”Ø **Tool Call Monitoring**: Track tool invocations and their arguments +- āœ… **Response Inspection**: Examine model responses and metadata +- āŒ **Error Logging**: Capture and display errors during execution +- šŸ“Š **Visual Panel**: Display a formatted summary of all events + +## Quick Start + +### Enable Dev Mode on Agent + +```typescript +import { agent, initDevPanel, showDevPanel } from '@agentage/sdk'; + +// Initialize dev panel (optional - automatically enabled in NODE_ENV=development) +initDevPanel({ + enabled: true, + logLevel: 'verbose', // 'verbose' | 'normal' | 'minimal' + showTimestamps: true, +}); + +// Enable dev mode on your agent +const assistant = agent('my-agent') + .model('gpt-4') + .instructions('You are helpful') + .devMode(true); // <-- Enable dev panel logging + +// Use agent normally +const response = await assistant.send('Hello!'); + +// Show the dev panel summary +showDevPanel(); +``` + +## Configuration + +### Dev Panel Config + +```typescript +interface DevPanelConfig { + enabled?: boolean; // Enable/disable the panel + logLevel?: 'verbose' | 'normal' | 'minimal'; // Logging verbosity + showTimestamps?: boolean; // Show timestamps on logs +} +``` + +### Initialization + +The dev panel can be initialized explicitly or will auto-initialize on first use: + +```typescript +// Explicit initialization +import { initDevPanel } from '@agentage/sdk'; + +const devPanel = initDevPanel({ + enabled: true, + logLevel: 'verbose', + showTimestamps: true, +}); +``` + +### Auto-Enable in Development + +The dev panel automatically enables when `NODE_ENV=development`: + +```bash +NODE_ENV=development npm start +``` + +## Usage Examples + +### Example 1: Basic Usage + +```typescript +import { agent, initDevPanel, showDevPanel } from '@agentage/sdk'; + +// Enable dev panel +initDevPanel({ enabled: true }); + +// Create agent with dev mode +const bot = agent('bot') + .model('gpt-4') + .devMode(true); // Enable debug logging + +await bot.send('Hello!'); + +// Display summary +showDevPanel(); +``` + +### Example 2: With Tools + +```typescript +import { agent, tool, initDevPanel, showDevPanel } from '@agentage/sdk'; +import { z } from 'zod'; + +// Initialize dev panel +initDevPanel({ enabled: true, logLevel: 'verbose' }); + +// Define a tool +const weatherTool = tool( + { + name: 'get_weather', + description: 'Get weather info', + inputSchema: { + city: z.string(), + }, + }, + async ({ city }) => ({ city, temp: 72, condition: 'Sunny' }) +); + +// Create agent with dev mode +const assistant = agent('weather-bot') + .model('gpt-4') + .tools([weatherTool]) + .devMode(true); + +// Tool calls will be logged +await assistant.send('What is the weather in SF?'); + +// Show all logged events +showDevPanel(); +``` + +### Example 3: Multiple Agents + +```typescript +import { agent, getDevPanel } from '@agentage/sdk'; + +// Get the global dev panel instance +const devPanel = getDevPanel(); + +// Create multiple agents with dev mode +const agent1 = agent('agent-1').model('gpt-4').devMode(true); +const agent2 = agent('agent-2').model('gpt-4').devMode(true); + +// Both agents log to the same dev panel +await agent1.send('Hello from agent 1'); +await agent2.send('Hello from agent 2'); + +// View all events from both agents +devPanel.show(); +``` + +## Dev Panel API + +### `initDevPanel(config?)` + +Initialize the global dev panel instance. + +```typescript +const devPanel = initDevPanel({ + enabled: true, + logLevel: 'normal', + showTimestamps: true, +}); +``` + +### `getDevPanel()` + +Get the global dev panel instance (creates one if it doesn't exist). + +```typescript +const devPanel = getDevPanel(); +``` + +### `showDevPanel()` + +Display the dev panel summary with all logged events. + +```typescript +showDevPanel(); +``` + +### `clearDevPanel()` + +Clear all logged events from the dev panel. + +```typescript +clearDevPanel(); +``` + +### Dev Panel Instance Methods + +#### `isEnabled(): boolean` + +Check if the dev panel is enabled. + +```typescript +const devPanel = getDevPanel(); +console.log('Enabled:', devPanel.isEnabled()); +``` + +#### `getEvents(): DevPanelEvent[]` + +Get all logged events. + +```typescript +const devPanel = getDevPanel(); +const events = devPanel.getEvents(); +console.log(`Total events: ${events.length}`); +``` + +#### `clear(): void` + +Clear all events. + +```typescript +const devPanel = getDevPanel(); +devPanel.clear(); +``` + +#### `show(): void` + +Display the visual panel with all events. + +```typescript +const devPanel = getDevPanel(); +devPanel.show(); +``` + +## Event Types + +The dev panel tracks different types of events: + +- **config**: Agent configuration +- **message**: Messages sent to agents +- **tool_call**: Tool invocations +- **response**: Model responses +- **error**: Errors during execution + +## Log Levels + +### `verbose` + +Logs everything including full data payloads: + +``` +[2026-01-06T10:30:00.000Z] šŸ”§ Agent Configuration: { name: 'bot', model: 'gpt-4', ... } +[2026-01-06T10:30:01.000Z] šŸ’¬ Message: { role: 'user', content: 'Hello' } +[2026-01-06T10:30:02.000Z] āœ… Response: { content: 'Hi there!', metadata: { ... } } +``` + +### `normal` (default) + +Logs events without configuration details: + +``` +[2026-01-06T10:30:00.000Z] šŸ’¬ Message: { role: 'user', content: 'Hello' } +[2026-01-06T10:30:01.000Z] āœ… Response: { content: 'Hi there!' } +``` + +### `minimal` + +Logs only messages, tool calls, responses, and errors (no config): + +``` +[2026-01-06T10:30:00.000Z] šŸ’¬ Message: { role: 'user', content: 'Hello' } +[2026-01-06T10:30:01.000Z] āœ… Response: { content: 'Hi there!' } +``` + +## Tips + +1. **Use in Development Only**: The dev panel is designed for development. Disable it in production. + +2. **Enable Selectively**: Only enable dev mode on agents you're debugging: + ```typescript + const debugAgent = agent('debug').devMode(true); + const prodAgent = agent('prod').devMode(false); + ``` + +3. **Clear Between Tests**: Clear the panel between test runs: + ```typescript + beforeEach(() => { + clearDevPanel(); + }); + ``` + +4. **Check Event Count**: Monitor event counts to ensure logging is working: + ```typescript + const devPanel = getDevPanel(); + console.log(`Events logged: ${devPanel.getEvents().length}`); + ``` + +5. **Timestamp Analysis**: Enable timestamps to analyze execution timing: + ```typescript + initDevPanel({ showTimestamps: true }); + ``` + +## Environment Variables + +### `NODE_ENV=development` + +Automatically enables the dev panel: + +```bash +NODE_ENV=development node app.js +``` + +## Complete Example + +See the [devpanel example](/examples/agent-sdk-devpanel-example) for a complete working example. + +## Troubleshooting + +### Dev Panel Not Logging + +1. Check if dev panel is enabled: + ```typescript + console.log('Enabled:', getDevPanel().isEnabled()); + ``` + +2. Verify dev mode is enabled on agent: + ```typescript + const agent = agent('bot').devMode(true); + ``` + +3. Check NODE_ENV: + ```bash + echo $NODE_ENV + ``` + +### No Output When Calling `showDevPanel()` + +The panel may be disabled. Enable it explicitly: + +```typescript +initDevPanel({ enabled: true }); +``` + +### Too Much Output + +Reduce log level: + +```typescript +initDevPanel({ logLevel: 'minimal' }); +``` + +Or disable timestamps: + +```typescript +initDevPanel({ showTimestamps: false }); +``` + +## Best Practices + +1. **Development Only**: Never enable dev panel in production +2. **Selective Enabling**: Only enable on agents you're debugging +3. **Clear Regularly**: Clear events between test runs +4. **Use Log Levels**: Choose appropriate log level for your needs +5. **Monitor Performance**: Dev panel adds overhead, disable when not needed + +## See Also + +- [Getting Started Guide](/docs/getting-started.md) +- [API Reference](/docs/api-reference.md) +- [Dev Panel Example](/examples/agent-sdk-devpanel-example) diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json index 8b411f1..ed464a9 100644 --- a/packages/sdk/tsconfig.json +++ b/packages/sdk/tsconfig.json @@ -5,5 +5,5 @@ "rootDir": "./src" }, "include": ["src/**/*"], - "exclude": ["node_modules", "dist", "**/*.test.ts"] + "exclude": ["node_modules", "dist"] }