initial
This commit is contained in:
299
readme.md
Normal file
299
readme.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# @push.rocks/smartagent
|
||||
A dual-agent agentic framework with Driver and Guardian agents for safe, policy-controlled AI task execution.
|
||||
|
||||
## Install
|
||||
```bash
|
||||
npm install @push.rocks/smartagent
|
||||
# or
|
||||
pnpm install @push.rocks/smartagent
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
SmartAgent implements a dual-agent architecture:
|
||||
|
||||
- **Driver Agent**: Executes tasks, reasons about goals, and proposes tool calls
|
||||
- **Guardian Agent**: Evaluates tool call proposals against a policy prompt, approving or rejecting with feedback
|
||||
|
||||
This design ensures safe tool use through AI-based policy evaluation rather than rigid programmatic rules.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
User Task + Guardian Policy Prompt
|
||||
|
|
||||
+---------------------------------------+
|
||||
| DualAgentOrchestrator |
|
||||
| |
|
||||
| +--------+ +------------+ |
|
||||
| | Driver |-------> | Guardian | |
|
||||
| | Agent | tool | Agent | |
|
||||
| | | call | | |
|
||||
| | Reason |<--------| Evaluate | |
|
||||
| | + Plan | approve | against | |
|
||||
| +--------+ /reject | policy | |
|
||||
| | +feedback+-----------+ |
|
||||
| v (if approved) |
|
||||
| +-----------------------------------+|
|
||||
| | Standard Tools ||
|
||||
| | Filesystem | HTTP | Shell | Browser|
|
||||
| +-----------------------------------+|
|
||||
+---------------------------------------+
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { DualAgentOrchestrator } from '@push.rocks/smartagent';
|
||||
|
||||
// Create orchestrator with Guardian policy
|
||||
const orchestrator = new DualAgentOrchestrator({
|
||||
openaiToken: 'sk-...',
|
||||
defaultProvider: 'openai',
|
||||
guardianPolicyPrompt: `
|
||||
FILE SYSTEM POLICY:
|
||||
- ONLY allow reading/writing within /tmp or the current working directory
|
||||
- REJECT operations on system directories or sensitive files
|
||||
|
||||
SHELL POLICY:
|
||||
- Allow read-only commands (ls, cat, grep, echo)
|
||||
- REJECT destructive commands (rm, mv, chmod) without explicit justification
|
||||
|
||||
FLAG any attempt to expose secrets or credentials.
|
||||
`,
|
||||
});
|
||||
|
||||
// Register standard tools
|
||||
orchestrator.registerStandardTools();
|
||||
|
||||
// Start the orchestrator (initializes all tools)
|
||||
await orchestrator.start();
|
||||
|
||||
// Run a task
|
||||
const result = await orchestrator.run('List all TypeScript files in the current directory');
|
||||
|
||||
console.log('Success:', result.success);
|
||||
console.log('Result:', result.result);
|
||||
console.log('Iterations:', result.iterations);
|
||||
|
||||
// Cleanup
|
||||
await orchestrator.stop();
|
||||
```
|
||||
|
||||
## Standard Tools
|
||||
|
||||
### FilesystemTool
|
||||
File and directory operations using `@push.rocks/smartfs`.
|
||||
|
||||
**Actions**: `read`, `write`, `append`, `list`, `delete`, `exists`, `stat`, `copy`, `move`, `mkdir`
|
||||
|
||||
```typescript
|
||||
// Example tool call by Driver
|
||||
<tool_call>
|
||||
<tool>filesystem</tool>
|
||||
<action>read</action>
|
||||
<params>{"path": "/tmp/config.json"}</params>
|
||||
<reasoning>Need to read the configuration file to understand the settings</reasoning>
|
||||
</tool_call>
|
||||
```
|
||||
|
||||
### HttpTool
|
||||
HTTP requests using `@push.rocks/smartrequest`.
|
||||
|
||||
**Actions**: `get`, `post`, `put`, `patch`, `delete`
|
||||
|
||||
```typescript
|
||||
<tool_call>
|
||||
<tool>http</tool>
|
||||
<action>get</action>
|
||||
<params>{"url": "https://api.example.com/data"}</params>
|
||||
<reasoning>Fetching data from the API endpoint</reasoning>
|
||||
</tool_call>
|
||||
```
|
||||
|
||||
### ShellTool
|
||||
Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection).
|
||||
|
||||
**Actions**: `execute`, `which`
|
||||
|
||||
```typescript
|
||||
<tool_call>
|
||||
<tool>shell</tool>
|
||||
<action>execute</action>
|
||||
<params>{"command": "ls", "args": ["-la", "/tmp"]}</params>
|
||||
<reasoning>Listing directory contents to find relevant files</reasoning>
|
||||
</tool_call>
|
||||
```
|
||||
|
||||
### BrowserTool
|
||||
Web page interaction using `@push.rocks/smartbrowser` (Puppeteer-based).
|
||||
|
||||
**Actions**: `screenshot`, `pdf`, `evaluate`, `getPageContent`
|
||||
|
||||
```typescript
|
||||
<tool_call>
|
||||
<tool>browser</tool>
|
||||
<action>getPageContent</action>
|
||||
<params>{"url": "https://example.com"}</params>
|
||||
<reasoning>Extracting text content from the webpage</reasoning>
|
||||
</tool_call>
|
||||
```
|
||||
|
||||
## Guardian Policy Examples
|
||||
|
||||
### Strict Security Policy
|
||||
```typescript
|
||||
const securityPolicy = `
|
||||
SECURITY POLICY:
|
||||
1. REJECT any file operations outside /home/user/workspace
|
||||
2. REJECT any shell commands that could modify system state
|
||||
3. REJECT any HTTP requests to internal/private IP ranges
|
||||
4. REJECT any attempts to read environment variables or credentials
|
||||
5. FLAG and REJECT obfuscated code execution
|
||||
|
||||
When rejecting, always explain:
|
||||
- What policy was violated
|
||||
- What would be a safer alternative
|
||||
`;
|
||||
```
|
||||
|
||||
### Development Environment Policy
|
||||
```typescript
|
||||
const devPolicy = `
|
||||
DEVELOPMENT POLICY:
|
||||
- Allow file operations only within the project directory
|
||||
- Allow npm/pnpm commands for package management
|
||||
- Allow git commands for version control
|
||||
- Allow HTTP requests to public APIs only
|
||||
- REJECT direct database modifications
|
||||
- REJECT commands that could affect other users
|
||||
|
||||
Always verify:
|
||||
- File paths are relative or within project bounds
|
||||
- Commands don't have dangerous flags (--force, -rf)
|
||||
`;
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
```typescript
|
||||
interface IDualAgentOptions {
|
||||
// Provider tokens (from @push.rocks/smartai)
|
||||
openaiToken?: string;
|
||||
anthropicToken?: string;
|
||||
perplexityToken?: string;
|
||||
groqToken?: string;
|
||||
xaiToken?: string;
|
||||
|
||||
// Provider selection
|
||||
defaultProvider?: TProvider; // For both Driver and Guardian
|
||||
guardianProvider?: TProvider; // Optional: separate provider for Guardian
|
||||
|
||||
// Agent configuration
|
||||
driverSystemMessage?: string; // Custom system message for Driver
|
||||
guardianPolicyPrompt: string; // REQUIRED: Policy for Guardian to enforce
|
||||
|
||||
// Limits
|
||||
maxIterations?: number; // Max task iterations (default: 20)
|
||||
maxConsecutiveRejections?: number; // Abort after N rejections (default: 3)
|
||||
}
|
||||
```
|
||||
|
||||
## Result Interface
|
||||
|
||||
```typescript
|
||||
interface IDualAgentRunResult {
|
||||
success: boolean; // Whether task completed successfully
|
||||
completed: boolean; // Task completion status
|
||||
result: string; // Final result or response
|
||||
iterations: number; // Number of iterations taken
|
||||
history: IAgentMessage[]; // Full conversation history
|
||||
status: TDualAgentRunStatus; // 'completed' | 'max_iterations_reached' | etc.
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Tools
|
||||
|
||||
Create custom tools by extending `BaseToolWrapper`:
|
||||
|
||||
```typescript
|
||||
import { BaseToolWrapper, IToolAction, IToolExecutionResult } from '@push.rocks/smartagent';
|
||||
|
||||
class MyCustomTool extends BaseToolWrapper {
|
||||
public name = 'custom';
|
||||
public description = 'My custom tool for specific operations';
|
||||
|
||||
public actions: IToolAction[] = [
|
||||
{
|
||||
name: 'myAction',
|
||||
description: 'Performs a custom action',
|
||||
parameters: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
input: { type: 'string', description: 'Input for the action' },
|
||||
},
|
||||
required: ['input'],
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
public async initialize(): Promise<void> {
|
||||
this.isInitialized = true;
|
||||
}
|
||||
|
||||
public async cleanup(): Promise<void> {
|
||||
this.isInitialized = false;
|
||||
}
|
||||
|
||||
public async execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult> {
|
||||
this.validateAction(action);
|
||||
this.ensureInitialized();
|
||||
|
||||
if (action === 'myAction') {
|
||||
return {
|
||||
success: true,
|
||||
result: { processed: params.input },
|
||||
};
|
||||
}
|
||||
|
||||
return { success: false, error: 'Unknown action' };
|
||||
}
|
||||
|
||||
public getCallSummary(action: string, params: Record<string, unknown>): string {
|
||||
return `Custom action "${action}" with input "${params.input}"`;
|
||||
}
|
||||
}
|
||||
|
||||
// Register custom tool
|
||||
orchestrator.registerTool(new MyCustomTool());
|
||||
```
|
||||
|
||||
## Supported Providers
|
||||
|
||||
| Provider | Driver | Guardian |
|
||||
|----------|:------:|:--------:|
|
||||
| OpenAI | Yes | Yes |
|
||||
| Anthropic | Yes | Yes |
|
||||
| Perplexity | Yes | Yes |
|
||||
| Groq | Yes | Yes |
|
||||
| Ollama | Yes | Yes |
|
||||
| XAI | Yes | Yes |
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
### Trademarks
|
||||
|
||||
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
|
||||
|
||||
### Company Information
|
||||
|
||||
Task Venture Capital GmbH
|
||||
Registered at District court Bremen HRB 35230 HB, Germany
|
||||
|
||||
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
|
||||
|
||||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|
||||
Reference in New Issue
Block a user