onchain-agent-server

v0.3.0-beta.12

Published

6 months ago

Server for Multimodal Agent.

0High
0Medium
0Low

heningyuan

Tarko Agent Server

Standard server implementation for deploying Tarko AI Agents as HTTP/WebSocket services.

Agent Server transforms any Tarko agent into a scalable web service with session management, real-time streaming, workspace isolation, and persistent storage.

Quick Start

npm install @tarko/agent-server

import { AgentServer } from '@tarko/agent-server';

const server = new AgentServer({
  appConfig: {
    agent: 'my-agent',
    workspace: './workspace',
    server: { port: 3000 },
    model: {
      provider: 'openai',
      id: 'gpt-4'
    }
  }
});

await server.start();
console.log('Agent server running on port 3000');

Core Features

🎯 Session Management

Create isolated agent sessions with persistent state and workspace isolation.

🌊 Streaming & Non-Streaming APIs

Support both real-time streaming responses and traditional request-response patterns.

💾 Flexible Storage

Choose from memory, file, or sqlite storage backends for session persistence.

🔌 WebSocket Support

Real-time bidirectional communication with automatic session reconnection.

📁 Workspace Isolation

Secure file access with session-scoped workspace management.

📊 AGIO Monitoring

Built-in analytics and monitoring integration for production deployments.

🔄 Session Sharing

Generate shareable session links with workspace asset uploading.

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   HTTP Client   │    │   WebSocket      │    │   Agent Core    │
│                 │◄──►│   Client         │◄──►│                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                     AgentServer                                 │
├─────────────────┬───────────────────┬───────────────────────────┤
│  Session Mgmt   │  EventStreamBridge │    Storage Provider       │
│                 │                   │                           │
│ • Create        │ • Real-time       │ • Memory/File/SQLite      │
│ • Update        │ • Event filtering │ • Session persistence     │
│ • Delete        │ • Client sync     │ • Event streaming         │
│ • Restore       │                   │                           │
└─────────────────┴───────────────────┴───────────────────────────┘

API Reference

Session Lifecycle

Create Session

POST /api/v1/sessions/create

Response: { sessionId: string }

Get Sessions

GET /api/v1/sessions

Response: { sessions: SessionItemInfo[] }

Session Details

GET /api/v1/sessions/details?sessionId={id}

Response: { session: SessionItemInfo & { active: boolean } }

Query Execution

Non-Streaming Query

POST /api/v1/sessions/query
Content-Type: application/json

{
  "sessionId": "session_123",
  "query": "What files are in my workspace?"
}

Response: { result: string }

Streaming Query

POST /api/v1/sessions/query/stream
Content-Type: application/json

{
  "sessionId": "session_123",
  "query": "Generate a detailed report"
}

Response: Server-Sent Events stream

One-Shot Execution

POST /api/v1/oneshot/query
Content-Type: application/json

{
  "query": "Quick analysis",
  "sessionName": "Analysis Session",
  "sessionTags": ["analysis", "quick"]
}

Response: { sessionId: string, result: string }

Session Control

Abort Query

POST /api/v1/sessions/abort
Content-Type: application/json

{ "sessionId": "session_123" }

Update Session

POST /api/v1/sessions/update
Content-Type: application/json

{
  "sessionId": "session_123",
  "name": "Updated Session Name",
  "tags": ["updated", "important"]
}

Delete Session

POST /api/v1/sessions/delete
Content-Type: application/json

{ "sessionId": "session_123" }

WebSocket Events

const socket = io('http://localhost:3000');

// Join a session
socket.emit('join-session', { sessionId: 'session_123' });

// Send query
socket.emit('send-query', {
  sessionId: 'session_123',
  query: 'Hello agent'
});

// Listen for agent events
socket.on('agent-event', (event) => {
  console.log('Agent event:', event);
});

Configuration

Basic Configuration

const server = new AgentServer({
  appConfig: {
    agent: 'my-agent',                    // Agent implementation
    workspace: './workspace',             // Workspace directory
    server: {
      port: 3000,                         // Server port
      exclusive: false,                   // Single session mode
      storage: {
        type: 'sqlite',                   // Storage backend
        path: './sessions.db'             // Storage path
      }
    },
    model: {
      provider: 'openai',                 // Model provider
      id: 'gpt-4',                       // Model ID
      providers: [                        // Available providers
        {
          name: 'openai',
          models: ['gpt-4', 'gpt-3.5-turbo'],
          baseURL: 'https://api.openai.com/v1'
        }
      ]
    }
  }
});

Storage Options

Memory Storage (Default)

storage: { type: 'memory' }

File Storage

storage: {
  type: 'file',
  path: './data/sessions'  // Directory for session files
}

SQLite Storage

storage: {
  type: 'sqlite',
  path: './sessions.db'    // SQLite database file
}

AGIO Monitoring

appConfig: {
  agio: {
    provider: 'https://agio.example.com/api/events'
  }
}

Session Sharing

appConfig: {
  share: {
    provider: 'https://share.example.com/api/upload'
  },
  webui: {
    type: 'static',
    staticPath: './dist/webui'
  }
}

Production Deployment

Docker Deployment

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
EXPOSE 3000

CMD ["node", "dist/server.js"]

Environment Variables

PORT=3000
WORKSPACE_PATH=/app/workspace
STORAGE_TYPE=sqlite
STORAGE_PATH=/app/data/sessions.db
MODEL_PROVIDER=openai
MODEL_ID=gpt-4
OPENAI_API_KEY=your-api-key

Health Checks

GET /api/v1/system/health

Response:

{
  "status": "healthy",
  "version": "0.3.0",
  "uptime": 3600,
  "sessions": {
    "active": 5,
    "total": 127
  },
  "storage": {
    "type": "sqlite",
    "path": "/app/data/sessions.db"
  }
}

Advanced Features

Exclusive Mode

Limit server to handle one session at a time:

server: { exclusive: true }

Workspace File Access

Access session workspace files:

GET /api/v1/sessions/workspace/files?sessionId=session_123&path=/images

Session Restoration

Restore sessions from storage:

POST /api/v1/sessions/restore
Content-Type: application/json

{ "sessionId": "session_123" }

Model Configuration Per Session

Sessions can override default model settings:

POST /api/v1/sessions/update
Content-Type: application/json

{
  "sessionId": "session_123",
  "metadata": {
    "modelConfig": {
      "provider": "anthropic",
      "modelId": "claude-3-opus"
    }
  }
}

Error Handling

All API endpoints return structured error responses:

{
  "error": "Session not found",
  "code": "SESSION_NOT_FOUND",
  "message": "Session session_123 does not exist",
  "details": {
    "sessionId": "session_123",
    "timestamp": 1704067200000
  }
}

Examples

Basic Usage

# Create session
curl -X POST http://localhost:3000/api/v1/sessions/create
# → {"sessionId":"abc123"}

# Send query
curl -X POST http://localhost:3000/api/v1/sessions/query \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"abc123","query":"Hello!"}'

# Stream query
curl -X POST http://localhost:3000/api/v1/sessions/query/stream \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"abc123","query":"Tell me a story"}'

WebSocket Client

import io from 'socket.io-client';

const socket = io('http://localhost:3000');

socket.emit('join-session', { sessionId: 'abc123' });
socket.emit('send-query', {
  sessionId: 'abc123',
  query: 'What can you help me with?'
});

socket.on('agent-event', (event) => {
  if (event.type === 'assistant_message') {
    console.log('Agent response:', event.content);
  }
});

Troubleshooting

Common Issues

Port already in use

lsof -ti:3000 | xargs kill -9

Storage permission errors

chmod 755 ./data
chown -R node:node ./data

Agent resolution failed

Verify agent implementation is available
Check workspace path exists and is readable
Ensure model provider credentials are configured

Debug Mode

appConfig: {
  logLevel: LogLevel.DEBUG
}

Monitoring

Enable request logging:

app.use(express.logger('combined'));

License

Apache-2.0