Sign in

TypeScript SDK — Quick Start

Install, configure, and make your first agent call with @cosmos/sdk

sdktypescriptquickstartgetting-started

Updated 2026-11-03

Verified 2026-11-03

@cosmos/sdk is a server-side TypeScript library for building AI-powered agent workflows on the Cosmos platform. It provides a unified client for authentication, agent execution, tool management, file storage, and observability.

Prerequisites

  • Node.js ≥ 18 (the SDK also runs under Bun)
  • A running Cosmos environment (local via ./manage.sh or cloud)
  • An access token (email/password login or OAuth2)

Installation

bash
npm install github:ey-org/cosmos-sdk-typescript#develop

dist/ is committed in the SDK repository because consumer apps install directly from GitHub pins.

Basic Setup

typescript
import { CosmosClient } from '@cosmos/sdk';

const cosmos = new CosmosClient({
  orgId: 'your-org-uuid',
  // Local development ports; point these at your deployment's service hosts elsewhere
  services: {
    user: 'http://localhost:8101',
    configurator: 'http://localhost:8100',
    adk: 'http://localhost:8103',
    storage: 'http://localhost:8107',
  },
  authManager: {
    tokens: {
      accessToken: '<your-access-token>',
      refreshToken: '<your-refresh-token>',
      expiresAt: new Date(Date.now() + 3600_000),
    },
  },
});

Each Cosmos service is reached at its own URL. Set gatewayUrl instead only when your deployment exposes every service behind one host as <gatewayUrl>/<service>. See Service URL Resolution.

Obtaining Tokens

Log in via the User Service to get an access/refresh token pair:

bash
curl -s -X POST http://localhost:8101/api/v1/users/login/ \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@cosmos.dev","password":"admin123"}'

Use the returned access_token and refresh_token in your CosmosClientConfig.

Service Authentication

For backend services and workers that authenticate with OAuth2 client credentials instead of a user token:

typescript
import { CosmosClient } from '@cosmos/sdk';

const cosmos = await CosmosClient.fromServiceCredentials(
  'your-client-id',
  '<client-secret>',
  {
    orgId: 'your-org-uuid',
    services: {
      user: 'http://localhost:8101', // token endpoint: <user>/oauth/token/
      configurator: 'http://localhost:8100',
      adk: 'http://localhost:8103',
    },
  },
);

The client acquires and auto-refreshes service tokens. See CosmosClient Reference — Service-to-Service Authentication for standalone token acquisition and advanced options.

Your First Agent Call

Send a message to a deployed agent and receive a response:

typescript
const response = await cosmos.adkClient.converse({
  agent_id: 'your-agent-uuid',
  agent_version: '1.0',
  user_id: 'user-123',
  query: 'What can you help me with?',
  channel: 'chat',
});

console.log(response.response.content);
// => "I can help you with..."
console.log('Session:', response.session_id);

Streaming via WebSocket (ADK v2)

For real-time streaming with local tool execution:

typescript
const result = await cosmos.sendMessageViaADK(null, 'Summarize my sales data', {
  agentId: 'your-agent-uuid',
  agentVersion: '1.0',
  sessionState: { projectId: 'project-uuid' },
  skills: [{ id: 'skill-uuid', version: '1.0' }],
  additionalCollectionIds: ['collection-uuid'],
  excludeTools: ['tool-to-skip'],
  onChunk: (text) => process.stdout.write(text),
  onToolCallArgsDelta: (name, path, delta) => console.log(name, path, delta),
});

console.log('\nSession:', result.sessionId);
cosmos.closeADKSession();

ADK manages context compaction for the session. Use onUsage to observe token usage as the turn progresses; see Context Compaction and Usage.

Browsing the Registry

List agents, tools, skills, and templates from the Configurator:

typescript
const agents = await cosmos.searchAgents({ query: 'sales' });
console.log(`Found ${agents.total} agents`);

const tools = await cosmos.searchTools({ type: 'api' });
console.log(`Found ${tools.total} API tools`);

const skills = await cosmos.searchSkills();
for (const skill of skills.items) {
  console.log(`${skill.name} — ${skill.description}`);
}

Clean Up

Always shut down the client when done to close WebSocket connections and flush observability events:

typescript
await cosmos.shutdown();

Next Steps