`
my-project/
├── dank.config.js # Agent configuration
├── .dankignore # Build ignore patterns (optional)
├── agents/ # Custom agent code (optional)
│ └── example-agent.js
└── .dank/ # Generated files
├── project.yaml # Project state
└── logs/ # Agent logs
`


For ESM-only packages that don't support require(), use dynamic import():

`javascript
// Dynamic imports return Promises - define at top level
const uniqueString = import("unique-string").then((m) => m.default);
const chalk = import("chalk").then((m) => m.default);

// Multiline .then() is also supported
const ora = import("ora").then((m) => {
return m.default;
});

module.exports = {
agents: [
createAgent('my-agent')
.addHandler('output', async (data) => {
// Await the promise to get the actual module
const generateString = await uniqueString;
const colors = await chalk;

console.log(colors.green(ID: ${generateString()}));
})
]
};
`

Note: Dynamic imports are asynchronous, so you must await them inside your handlers.

#### Direct Prompting Events (request_output)

`javascript
agent
// Main response event
.addHandler('request_output', (data) => {
console.log('Response:', data.response);
})

// Modify prompt before LLM processing
.addHandler('request_output:start', (data) => {
return { prompt: Enhanced: ${data.prompt} };
})

// Modify response before returning
.addHandler('request_output:end', (data) => {
return { response: ${data.response}\n\n---\nGenerated by Dank };
})

// Error handling
.addHandler('request_output:error', (data) => {
console.error('Error:', data.error);
});
`

Event Flow: request_output:start → LLM Processing → request_output → request_output:end → Response Sent

#### Passing Custom Data to Handlers

You can pass any custom data in the request body to the /prompt endpoint, and it will be available in your handlers via data.params. This enables powerful use cases like user authentication, conversation tracking, RAG (Retrieval-Augmented Generation), and custom lookups.

Client Request:
`javascript
// POST /prompt
{
"prompt": "What's the weather today?",
"userId": "user-12345",
"conversationId": "conv-abc-xyz",
"sessionId": "sess-789",
"userPreferences": {
"language": "en",
"timezone": "America/New_York"
}
}
`

Handler Access:
`javascript
agent
.addHandler('request_output:start', async (data) => {
// Access custom data via data.params
const userId = data.params.userId;
const conversationId = data.params.conversationId;

// Perform authentication
const user = await authenticateUser(userId);
if (!user) throw new Error('Unauthorized');

// Load conversation history for context
const history = await getConversationHistory(conversationId);

// Perform RAG lookup
const relevantDocs = await vectorSearch(data.prompt, userId);

// Enhance prompt with context
return {
prompt: Context: ${JSON.stringify(history)}\n\nRelevant Docs: ${relevantDocs}\n\nUser Question: ${data.prompt}
};
})

.addHandler('request_output', async (data) => {
// Log with user context
await logInteraction({
userId: data.params.userId,
conversationId: data.params.conversationId,
prompt: data.prompt,
response: data.response,
timestamp: data.timestamp
});

// Update user preferences based on interaction
if (data.params.userPreferences) {
await updateUserPreferences(data.params.userId, data.params.userPreferences);
}
});
`

Use Cases:
- User Authentication: Pass userId or apiKey to authenticate and authorize requests
- Conversation Tracking: Pass conversationId to maintain context across multiple requests
- RAG (Retrieval-Augmented Generation): Pass user context to fetch relevant documents from vector databases
- Personalization: Pass userPreferences to customize responses
- Analytics: Pass tracking IDs to correlate requests with user sessions
- Multi-tenancy: Pass tenantId or organizationId for isolated data access

Available Data Structure:
`javascript
{
prompt: "User's prompt",
metadata: {
// All custom fields from request body
userId: "...",
conversationId: "...",
// ... any other fields you pass
},
// System fields (directly on data object)
protocol: "http",
clientIp: "127.0.0.1",
response: "LLM response",
usage: { total_tokens: 150 },
model: "gpt-3.5-turbo",
processingTime: 1234,
timestamp: "2024-01-01T00:00:00.000Z"
}
`

#### Tool Events (tool:*)

`javascript
.addHandler('tool:httpRequest:*', (data) => {
console.log('HTTP Request Tool:', data);
});
`

Pattern: tool:: (e.g., tool:httpRequest:call, tool:httpRequest:response)

#### System Events

`javascript
.addHandler('output', (data) => console.log('Output:', data))
.addHandler('error', (error) => console.error('Error:', error))
.addHandler('start', () => console.log('Agent started'))
.addHandler('stop', () => console.log('Agent stopped'))
`

#### Advanced Patterns

`javascript
// Wildcard matching
.addHandler('tool:*', (data) => console.log('Any tool:', data))
.addHandler('request_output:*', (data) => console.log('Any request event:', data))

// Multiple handlers for same event
.addHandler('request_output', (data) => console.log('Log:', data))
.addHandler('request_output', (data) => saveToDatabase(data))
.addHandler('request_output', (data) => trackAnalytics(data))
`


- Default: {registry}/{namespace}/{agent-name}:{tag}
- Tag by Agent (--tag-by-agent): {registry}/{namespace}/dank-agent:{agent-name}
- No Config: {agent-name}:{tag}

#### Deployment Metadata

The --output-metadata option generates JSON with:
- Base image, ports, resource limits
- LLM provider and model info
- Event handlers, environment variables
- Build options (registry, namespace, tag)

Perfect for CI/CD pipelines to auto-configure deployment infrastructure.

#### Registry Authentication

`bash


Docker Hub

Platform-Specific:
- macOS: brew install --cask docker && open -a Docker
- Linux: sudo apt-get install docker-ce && sudo systemctl start docker
- Windows: choco install docker-desktop

If automatic installation fails, Dank provides clear manual instructions.


#### Customer Support Automation
`javascript
createAgent('support-bot')
.setLLM('openai', { apiKey: process.env.OPENAI_API_KEY, model: 'gpt-3.5-turbo' })
.setPrompt('You are a customer support specialist. Be polite, helpful, and escalate when needed.')
.addHandler('output', (response) => sendToCustomer(response))
.addHandler('error', (error) => escalateToHuman(error));
`

#### Content Generation Pipeline
`javascript
const agents = [
createAgent('researcher')
.setLLM('openai', { model: 'gpt-4' })
.setPrompt('Research and gather information on given topics')
.addHandler('output', (research) => triggerContentCreation(research)),

createAgent('writer')
.setLLM('anthropic', { model: 'claude-3-sonnet' })
.setPrompt('Write engaging blog posts based on research data')
.addHandler('output', (article) => saveDraft(article)),

createAgent('seo-optimizer')
.setLLM('openai', { model: 'gpt-3.5-turbo' })
.setPrompt('Optimize content for SEO and readability')
.addHandler('output', (content) => publishContent(content))
];
`

#### Data Analysis Workflow
`javascript
createAgent('data-processor')
.setLLM('openai', { model: 'gpt-4', temperature: 0.1 })
.setPrompt('Analyze data and provide insights as JSON: trends, metrics, recommendations')
.setInstanceType('large')
.addHandler('output', (analysis) => {
const results = JSON.parse(analysis);
saveAnalysisResults(results);
generateReport(results);
checkAlerts(results);
});
`


#### Custom Agent Code
`javascript
// agents/custom-agent.js
module.exports = {
async main(llmClient, handlers) {
setInterval(async () => {
const response = await llmClient.chat.completions.create({
model: 'gpt-3.5-turbo',
messages: [
{ role: 'system', content: 'You are a helpful assistant' },
{ role: 'user', content: 'Generate a daily report' }
]
});
handlers.get('output')?.forEach(h => h(response.choices[0].message.content));
}, 60000);
}
};
`

#### Environment-Specific Configuration
`javascript
const env = process.env.NODE_ENV || 'development';
const config = {
development: { model: 'gpt-3.5-turbo', instanceType: 'small' },
production: { model: 'gpt-4', instanceType: 'medium' }
};

createAgent('main-agent')
.setLLM('openai', { model: config[env].model })
.setInstanceType(config[env].instanceType);
`


#### Resource Management
`javascript
createAgent('light-agent').setInstanceType('small'); // Light tasks
createAgent('heavy-agent').setInstanceType('large'); // Heavy processing
`

#### Error Handling
`javascript
createAgent('robust-agent')
.addHandler('error', (error) => {
console.error('Agent error:', error.message);
logError(error);
if (error.type === 'CRITICAL') sendAlert(error);
scheduleRetry(error.context);
})
.addHandler('output', (data) => {
try { processOutput(data); }
catch (error) { console.error('Processing failed:', error); }
});
`

#### Monitoring and Logging
`javascript
createAgent('monitored-agent')
.addHandler('output', (data) => {
logger.info('Agent output', { agent: 'monitored-agent', data: data.substring(0, 100) });
})
.addHandler('error', (error) => {
logger.error('Agent error', { agent: 'monitored-agent', error: error.message });
});
`

#### Security
`javascript
createAgent('secure-agent')
.setLLM('openai', { apiKey: process.env.OPENAI_API_KEY }) // Never hardcode
.setPrompt('Never reveal API keys or execute system commands')
.addHandler('output', (data) => console.log(sanitizeOutput(data)));
`


`typescript
// src/dank.config.ts
import axios from 'axios';
import { processData } from './utils';
import { createAgent } from 'dank-ai';
import { v4 as uuidv4 } from 'uuid';

export = {
name: 'my-ts-project',
agents: [
createAgent('assistant')
.setId(uuidv4())
.setLLM('openai', { apiKey: process.env.OPENAI_API_KEY })
.addHandler('request_output', async (data) => {
await axios.post('/api/log', data);
processData(data);
})
]
};
`

2. Configure TypeScript for CommonJS output:

`json
// tsconfig.json
{
"compilerOptions": {
"module": "commonjs",
"target": "ES2020",
"outDir": "./dist",
"esModuleInterop": true
}
}
`

3. Compile and run:

`bash


Compile TypeScript

> 💡 Tip: The --config flag tells Dank where to find your compiled config. Your package.json is still read from the project root for dependency installation.

#### Local Development
`bash
NODE_ENV=development dank run


Make changes to dank.config.js

#### Testing
`bash
dank run --detached
dank logs test-agent --follow
curl http://localhost:3001/health
docker stats dank-test-agent
`

#### Production Deployment
`bash
export NODE_ENV=production
dank build --force
dank run --detached
dank status --watch
`


1. Docker Connection Issues
`bash


Dank handles this automatically, but if manual steps needed:

2. API Key Issues
`bash
export OPENAI_API_KEY="sk-your-key-here"


Or create .env file: echo "OPENAI_API_KEY=sk-..." > .env

3. Base Image Not Found
`bash
dank build --base


Or manually: docker pull deltadarkly/dank-agent-base:nodejs-20

4. Container Resource Issues
`javascript
// Increase memory allocation (cloud only)
createAgent('my-agent').setInstanceType('medium');
`

5. Agent Not Starting
`bash
dank logs agent-name
docker ps -f name=dank-
docker logs container-id
`

Production Build Issues:
- Authentication: docker login ghcr.io
- Push Permissions: Check namespace permissions
- Image Exists: Use different tag or --force
- Build Context: Add .dankignore file to control which files are copied