#Server

The Agent TARS Server is a server-side component in the Agent TARS ecosystem built on top of Agent TARS Core. It includes capabilities such as session storage management and a Web UI:

agent-tars serve

#Basic Concepts

Agent TARS Server handles two main concepts:

1. Session: Represents a complete Agent TARS interaction context, containing message history, tool calls, and state information
2. Query: A single request executed within a session, which can be text or multimodal content

By default, Agent TARS Server's base path is /api, through which you can access various server endpoints.

#Server Configuration

Agent TARS Server offers multiple configuration options, including port settings, storage configuration, working directory, and sharing options. These configurations can be set through the Agent TARS configuration file.

agent-tars serve --port 8888

// agent-tars.config.ts
export default {
  server: {
    port: 8888,
    // Other server configurations...
  },
  // Other configurations implemented by server.
};

#Session Management API

Agent TARS Server provides a complete session lifecycle management API:

#Create Session

Create a new Agent session:

POST /api/sessions/create

Response:

{
  "sessionId": "unique-session-id"
}

#Get Session List

Retrieve all sessions:

GET /api/sessions

Response:

{
  "sessions": [
    {
      "id": "session-id-1",
      "createdAt": 1622548800000,
      "updatedAt": 1622548800000,
      "name": "Session Name"
    }
    // ...more sessions
  ]
}

#Get Session Details

Get detailed information for a specific session:

GET /api/sessions/details?sessionId=session-id

#Get Session Status

Get the current running status of a session:

GET /api/sessions/status?sessionId=session-id

Response:

{
  "sessionId": "session-id",
  "status": {
    "isProcessing": false,
    "state": "idle"
  }
}

#Get Session Events

Retrieve historical events for a specific session:

GET /api/sessions/events?sessionId=session-id

#Update Session

Update session metadata:

POST /api/sessions/update

Request body:

{
  "sessionId": "session-id",
  "name": "New Session Name",
  "tags": ["tag1", "tag2"]
}

#Delete Session

Delete a specific session and all its events:

POST /api/sessions/delete

Request body:

{
  "sessionId": "session-id"
}

#Query Execution API

Agent TARS Server supports two query execution modes: standard mode and streaming mode.

#Execute Standard Query

POST /api/sessions/query

Request body:

{
  "sessionId": "session-id",
  "query": "Hello, Agent TARS!"
}

For multimodal queries, query can be an array of content parts with text and images:

{
  "sessionId": "session-id",
  "query": [
    { "type": "text", "text": "What's in this image?" },
    { 
      "type": "image_url", 
      "image_url": {
        "url": "data:image/jpeg;base64,..."
      }
    }
  ]
}

#Execute Streaming Query

Streaming queries allow you to get real-time responses:

POST /api/sessions/query/stream

The request body is the same as for standard queries, but responses will be streamed in Server-Sent Events (SSE) format.

#Abort Query

Interrupt a currently executing query:

POST /api/sessions/abort

Request body:

{
  "sessionId": "session-id"
}

#Sharing Functionality

Agent TARS Server provides powerful session sharing capabilities, allowing export and sharing of session history.

#Get Sharing Configuration

GET /api/share/config

#Share Session

POST /api/sessions/share

Request body:

{
  "sessionId": "session-id",
  "upload": true
}

Response:

{
  "success": true,
  "url": "https://share-provider.com/shared-session-id"
}

#WebSocket Communication

In addition to RESTful API, Agent TARS Server also provides WebSocket interfaces for real-time bidirectional communication.

#Connect to a Session

// Client code
const socket = io('http://localhost:8888');

// Join a specific session
socket.emit('join-session', 'session-id');

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

// Send a query
socket.emit('send-query', {
  sessionId: 'session-id',
  query: 'Hello, Agent TARS!'
});

// Abort a query
socket.emit('abort-query', { sessionId: 'session-id' });

#Usage

#Using from Agent TARS CLI

Start the server using CLI:

agent-tars serve --port 8888

You can specify server options in the configuration file:

// agent-tars.config.ts
export default {
  server: {
    port: 8888,
    open: true,  // Automatically open browser
  }
};

#Middleware Extensions

Agent TARS Server is based on Express and Connect middleware architecture and can extend server functionality through APIs:

// In a custom script
import { AgentTARSServer } from '@agent-tars/server';

const server = new AgentTARSServer(config);
const app = server.getApp();

// Add custom middleware
app.use('/custom-endpoint', (req, res) => {
  res.json({ message: 'Hello from custom endpoint!' });
});

await server.start();

#Event Stream Processing

Agent TARS Server uses structured event streams for communication. Each event has a specific type and format, such as: user messages, assistant replies, tool calls, and system events.

Here's a typical event stream:

[
  { type: 'user_message', content: 'User query', timestamp: 1622548800000, id: '...' },
  { type: 'assistant_streaming_message', content: 'Assistant', timestamp: 1622548800100, id: '...' },
  { type: 'tool_call', name: 'web_search', arguments: {...}, timestamp: 1622548800200, id: '...' },
  { type: 'tool_result', name: 'web_search', content: {...}, timestamp: 1622548800300, id: '...' },
  { type: 'assistant_message', content: 'Final response', timestamp: 1622548800400, id: '...' }
]