Runtime SDK for building AI agents with LLM, embedding, approval, cache, logging, and progress APIs. Includes pause/resume mechanism for async operations.
A runtime SDK for building AI agents with LLM calls, embeddings, approvals, caching, logging, and progress reporting. Part of the Agent Tool Protocol (ATP).
This skill helps you use the `@mondaydotcomorg/atp-runtime` package to build AI agents that can:
Install the package:
```bash
npm install @mondaydotcomorg/atp-runtime
```
**Call LLM:**
```typescript
const response = await atp.llm.call({
prompt: 'What is the capital of France?',
model: 'gpt-4',
temperature: 0.7,
systemPrompt: 'You are a helpful assistant'
});
```
**Extract structured data:**
```typescript
const user = await atp.llm.extract({
prompt: 'Extract user info: John Doe, [email protected]',
schema: {
type: 'object',
properties: {
name: { type: 'string' },
email: { type: 'string' }
},
required: ['name', 'email']
}
});
// Returns: { name: 'John Doe', email: '[email protected]' }
```
**Classify text:**
```typescript
const category = await atp.llm.classify({
text: 'This product is amazing!',
categories: ['positive', 'negative', 'neutral']
});
// Returns: 'positive'
```
**Generate and store embedding:**
```typescript
const embeddingId = await atp.embedding.embed('Important document content');
```
**Search by similarity:**
```typescript
const results = await atp.embedding.search('find similar documents', {
topK: 5,
minSimilarity: 0.7
});
// Returns: [{ id: string, text: string, similarity: number }, ...]
```
**Calculate similarity:**
```typescript
const similarity = await atp.embedding.similarity(vec1, vec2);
```
**Manage embeddings:**
```typescript
const all = await atp.embedding.getAll();
const count = await atp.embedding.count();
await atp.embedding.clear();
```
**Request human approval:**
```typescript
const result = await atp.approval.request('Delete all user data?', {
critical: true,
affectedUsers: 150
});
if (result.approved) {
await deleteData();
} else {
return { cancelled: true, reason: result.response };
}
```
**Set/get cache values:**
```typescript
await atp.cache.set('user:123', userData, 3600); // TTL in seconds
const cached = await atp.cache.get('user:123');
const exists = await atp.cache.has('user:123');
await atp.cache.delete('user:123');
```
**Structured logging:**
```typescript
atp.log.trace('Detailed trace', { requestId: '123' });
atp.log.debug('Debug info', { state });
atp.log.info('User logged in', { userId: '456' });
atp.log.warn('Deprecated API used', { api: 'v1' });
atp.log.error('Failed to connect', { error, retries: 3 });
atp.log.fatal('System crash', { reason });
```
**Report progress:**
```typescript
atp.progress.report({
current: 5,
total: 10,
message: 'Processing items...',
metadata: {
itemsPerSecond: 2.5
}
});
```
```typescript
const items = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
const results = [];
atp.log.info('Starting fruit analysis', { count: items.length });
for (let i = 0; i < items.length; i++) {
atp.progress.report({
current: i + 1,
total: items.length,
message: `Processing ${items[i]}`
});
// Call LLM for each item
const analysis = await atp.llm.call({
prompt: `Analyze this fruit: ${items[i]}`
});
// Store embedding for semantic search
const embeddingId = await atp.embedding.embed(analysis);
// Cache result
await atp.cache.set(`analysis:${items[i]}`, analysis, 3600);
results.push({ fruit: items[i], analysis, embeddingId });
}
// Request approval before returning
const approval = await atp.approval.request('Analysis complete. Proceed with storage?', {
resultCount: results.length
});
if (!approval.approved) {
atp.log.warn('User rejected storage');
return { cancelled: true };
}
atp.log.info('Analysis complete', { results: results.length });
return results;
```
The runtime uses a pause/resume mechanism for async operations:
1. Agent code calls `atp.llm.call()`
2. Runtime pauses execution
3. Server requests LLM callback from client
4. Client calls external LLM API
5. Client resumes execution with result
6. Runtime restores state and returns result
**Initialize runtime components:**
```typescript
import {
setClientLLMCallback,
initializeCache,
initializeApproval,
initializeVectorStore,
initializeLogger
} from '@mondaydotcomorg/atp-runtime';
setClientLLMCallback({
call: async (prompt, options) => {
// Implement LLM call
}
});
initializeCache(cacheProvider);
initializeApproval({
request: async (message, context) => {
// Implement approval
}
});
initializeVectorStore(embeddingHandler);
initializeLogger({ level: 'info', pretty: true });
```
**Enable replay mode for testing:**
```typescript
import { setReplayMode } from '@mondaydotcomorg/atp-runtime';
setReplayMode(true);
// LLM calls return cached results instead of pausing
```
**Error handling:**
```typescript
import { PauseExecutionError, isPauseError } from '@mondaydotcomorg/atp-runtime';
try {
const result = await atp.llm.call({ prompt: 'Hello' });
} catch (error) {
if (isPauseError(error)) {
console.log('Paused for:', error.callbackType);
} else {
throw error;
}
}
```
Import TypeScript types for all APIs:
```typescript
import type {
LLMCallOptions,
LLMExtractOptions,
LLMClassifyOptions,
EmbeddingSearchOptions,
EmbeddingSearchResult,
ApprovalRequest,
ApprovalResponse,
ProgressUpdate
} from '@mondaydotcomorg/atp-runtime';
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/atp-runtime-sdk/raw