ADKClient Reference

import type { ADKConverseRequest, ADKConverseResponse } from '@cosmos/sdk';

const response: ADKConverseResponse = await cosmos.adkClient.converse({
  agent_id: 'agent-uuid',
  agent_version: '1.0',
  user_id: 'user-123',
  query: 'What were our Q1 sales?',
  channel: 'chat',
  language: 'en',
  reasoning_event: true,
});

console.log(response.response.content);
console.log('Session ID:', response.session_id);
console.log('Final?', response.response.is_final);

// Reasoning events (if requested)
for (const event of response.events ?? []) {
  console.log(`[${event.event}]`, event.files ?? '');
}

const result = await cosmos.sendMessageViaADK(null, 'Analyze this data', {
  agentId: 'agent-uuid',
  agentVersion: '1.0',
  providerId: 'azure_openai',
  modelId: 'gpt-4o',
  temperature: 0.7,
  maxOutputTokens: 2048,
  skills: [{ id: 'skill-uuid', version: '1.0' }],
  sessionState: { projectId: 'project-uuid', workbench: 'sap-adt' },
  additionalInstructions: 'Prefer concise answers.',
  additionalCollectionIds: ['collection-uuid'],
  excludeTools: ['tool-to-skip'],
  appName: 'support-workbench',
  onChunk: (text) => process.stdout.write(text),
  onToolCallArgsDelta: (name, jsonPath, delta) => console.log(name, jsonPath, delta),
});

console.log('\nSession:', result.sessionId);
console.log('End conversation?', result.endConversation);

import { ADKV2StreamSession } from '@cosmos/sdk';

const session = new ADKV2StreamSession(
  'ws://localhost:8103/api/v1/adk/converse/v2', // local ADK; use wss://<adk-host>/... when deployed
  orgId,
  () => cosmos.auth.getAccessToken(),
  cosmos.toolManager.getLocalHandlers(),
  projectId, // optional; sent as X-Project-Id on the handshake
);

const result = await session.startAndRun(
  {
    userId: 'user-123',
      query: 'Hello',
    agentId: 'agent-uuid',
    agentVersion: '1.0',
    sessionState: { projectId: 'project-uuid' },
  },
  {
    onChunk: (text) => process.stdout.write(text),
    onToolStart: (name) => console.log(`\n🔧 ${name}...`),
    onToolComplete: (name, result) => console.log(`✅ ${name} done`),
    onToolCallArgsDelta: (name, path, delta) => console.log(name, path, delta),
    onReasoning: (content) => console.log(`💭 ${content}`),
    onError: (code, msg, fatal) => console.error(`Error [${code}]: ${msg}`),
  },
);

// Follow-up turn on same WebSocket
const result2 = await session.sendQuery('Tell me more', {
  onChunk: (text) => process.stdout.write(text),
});

// Cancel current turn
session.cancel();

// Clean up
session.close();

await cosmos.sendMessageViaADK(sessionId, 'Continue', {
  onUsage: (usage) => {
    // promptTokens is the live context size of the call that just completed
    console.log(usage.promptTokens, usage.completionTokens);
    console.log(usage.cumulativePromptTokens, usage.cumulativeCompletionTokens);
    // contextLimit: model context window reported by ADK
    // tokenThreshold: compaction trigger, only when the session has one configured
    console.log(usage.contextLimit, usage.tokenThreshold);
  },
});

const sessions = await cosmos.adkClient.listSessions({
  user_id: 'user-123',
  agent_id: 'agent-uuid',
  limit: 20,
});

for (const session of sessions) {
  console.log(`${session.id} — ${session.app_name} — ${session.create_time}`);
}

const events = await cosmos.adkClient.getSessionEvents(sessionId, {
  skip: 0,
  limit: 50,
});

for (const event of events) {
  console.log(`[${event.author}] ${event.timestamp}`, event.content);
}

await cosmos.adkClient.updateSessionMetadata(sessionId, {
  name: 'Q1 Sales Analysis',
  pinned: true,
  tags: ['sales', 'q1'],
});

await cosmos.adkClient.addEvent({
  app_name: 'my-app',
  user_id: 'user-123',
  session_id: sessionId,
  content: 'New data has been uploaded to the knowledge base.',
  state_delta: { kb_updated: true },
});

const llmResponse = await cosmos.adkClient.callLLM({
  provider: 'azure_openai',
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Translate "hello" to French.' },
  ],
  temperature: 0.3,
  max_tokens: 100,
});

console.log(llmResponse.message.content);

const { request_id } = await cosmos.adkClient.submitAsync({
  agent_id: 'agent-uuid',
  agent_version: '1.0',
  user_id: 'user-123',
  query: 'Generate a comprehensive market analysis report',
  callback_url: 'https://my-app.com/webhooks/adk',
  callback_method: 'POST',
});

console.log('Queued:', request_id);

const status = await cosmos.adkClient.getAsyncStatus(request_id);
console.log(status.status); // 'queued' | 'processing' | 'completed' | 'failed'

if (status.status === 'completed') {
  console.log(status.response?.content);
}

const final = await cosmos.adkClient.pollAsyncUntilDone(request_id, 2000, 120_000);
if (final.status === 'completed') {
  console.log(final.response?.content);
} else {
  console.error(final.error_message);
}

const list = await cosmos.adkClient.listAsyncRequests({
  user_id: 'user-123',
  status: 'completed',
  limit: 10,
});

console.log(`${list.total} total, showing ${list.requests.length}`);

// From a description
const result = await cosmos.generateSkills({
  source: 'description',
  description: 'A skill that helps users debug failing API calls',
  maxSkills: 3,
});

for (const proposal of result.proposals) {
  console.log(`${proposal.name}: ${proposal.description}`);
  console.log(`  Rationale: ${proposal.rationale}`);
  console.log(`  Instructions: ${proposal.instructions.slice(0, 100)}...`);
}

// From an existing agent prompt
const result2 = await cosmos.generateSkills({
  source: 'agent_prompt',
  agentId: 'agent-uuid',
  agentVersion: '1.0',
});

import type {
  ADKConverseRequest,
  ADKConverseResponse,
  ADKConverseResponsePayload,
  ADKReasoningEvent,
  ADKAddEventRequest,
  ADKAddEventResponse,
  ADKSession,
  ADKSessionEvent,
  ADKSessionsListParams,
  ADKSessionEventsParams,
  ADKAsyncSubmitRequest,
  ADKAsyncSubmitResponse,
  ADKAsyncRequestStatus,
  ADKAsyncStatusResponse,
  ADKAsyncListParams,
  ADKAsyncListResponse,
  ADKV2SendOptions,
  ADKV2ExecutionContext,
  ADKV2ImageAttachment,
  ADKV2TurnCallbacks,
  ADKV2TurnResult,
  ADKV2ToolDefinition,
  ADKV2ToolEventMeta,
  ADKV2Usage,
  GenerateSkillsInput,
  SkillProposal,
  GenerateSkillsResponse,
} from '@cosmos/sdk';