Quickstart: Your First Agent Server

This guide takes you from zero to a running, Sharely-connected agent server.

Prerequisites

  • Node.js 20+
  • A Sharely.ai workspace and a workspace API key (sk-sharely-...) — see Authentication

1. Install

npm i @sharelyai/server @sharelyai/protocol

@sharelyai/server is the runtime; @sharelyai/protocol provides the types-only Handler and AgentEvent definitions you write against.

2. Write a minimal server

import { createSharelyServer } from '@sharelyai/server';
 
const app = createSharelyServer({
  apiUrl: process.env.SHARELY_API_URL!,            // https://api.sharely.ai
  workspaceId: process.env.SHARELY_WORKSPACE_ID!,
  workspaceApiKey: process.env.SHARELY_WORKSPACE_API_KEY!,
  handler: async function* (input) {
    yield { type: 'message_start', role: 'assistant', model: 'echo-v1' };
    yield { type: 'content_delta', delta: `Echo: ${input.message}` };
    yield {
      type: 'message_end',
      finishReason: 'stop',
      tokenUsage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
    };
  },
});
 
app.listen(8080);

That's a complete, working agent server. The SDK owns HTTP, auth, token validation, message persistence, and SSE encoding — your handler only produces the answer.

Configuration options

createSharelyServer(options):

OptionRequiredDefaultPurpose
apiUrl✓—Sharely platform base URL (e.g. https://api.sharely.ai)
workspaceId✓—Your Sharely workspace ID
workspaceApiKey✓—Workspace API key (sk-sharely-*). Used to validate incoming user tokens and to call the platform on your behalf
handler✓—Your Handler, or a per-request factory (req) => Handler
allowedOriginsunsetCORS allowlist (string or string[]). If unset, cross-origin browser requests are disabled — set it for browser clients
enableProxytrueCatch-all reverse proxy to the platform for unmatched routes. Set false to 404 instead
loggerconsoleA Logger (debug/info/warn/error) to integrate with your stack
rateLimitPerMinute20Per-auth-key rate limit on the chat route
fetcherTimeoutMs30000Upstream request timeout
validateIncomingTokentrueValidate the incoming user token before invoking the Handler. Disable only for trusted test fixtures

3. Understand the auth model

The SDK uses a two-key system:

  1. Workspace API key (sk-sharely-*) — authenticates your server to the Sharely platform. Keep it server-side, never in a browser.
  2. User JWT — arrives on each incoming request and identifies the end user. The SDK validates it and forwards it on every platform call, so persistence and RAG are scoped to that user's role automatically.

The SDK never mints user tokens — token issuance stays with the Sharely control plane (see Web Control authentication).

4. Run it

SHARELY_API_URL=https://api.sharely.ai \
SHARELY_WORKSPACE_ID=your-workspace-id \
SHARELY_WORKSPACE_API_KEY=sk-sharely-... \
node server.mjs

Your server exposes:

  • POST /agent/threads/:threadId/chat — the chat turn entrypoint the platform calls
  • GET /health — liveness probe
  • A catch-all reverse proxy to apiUrl (disable with enableProxy: false)

5. Register your agent server with your workspace

Tell Sharely.ai where your server lives using the Agent API:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/servers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-custom-agent",
    "url": "https://agent.example.com"
  }'

Once registered, the platform dispatches chat turns for threads bound to your agent server, and Web Control renders the streamed response — thinking steps, tool calls, citations and all.

6. Production checklist

  • Set allowedOrigins if browsers call your server directly
  • Use HTTPS — the platform calls your server over the public internet
  • Install graceful shutdown so in-flight SSE streams drain on deploy:
import { createSharelyServer, installGracefulShutdown } from '@sharelyai/server';
 
const app = createSharelyServer({ /* … */ });
const server = app.listen(8080);
installGracefulShutdown(server);
  • Pass a logger to integrate with your observability stack
  • Keep validateIncomingToken: true (the default) in production

Try it without any keys

The SDK repository ships runnable examples with offline smoke tests that mock the platform — no API keys needed:

git clone https://github.com/sharelyai/sharely-server-sdk.git
cd sharely-server-sdk
npm install
npx turbo run build
node examples/raw-streaming/smoke.mjs

See Adapters & Examples for the full list.

Next Steps