FaosClient

The main entry point for the FAOS TypeScript SDK. Provides shortcut-based agent invocation with both standard and streaming responses.

import { FaosClient } from '@faos/sdk';

Constructor

new FaosClient(options: FaosClientOptions)

FaosClientOptions

Property	Type	Default	Description
apiKey	string	required	FAOS API key for authentication
baseUrl	string	"https://api.faosx.ai"	API base URL
timeout	number	30000	Request timeout in milliseconds

Example

const client = new FaosClient({ apiKey: 'sk-your-api-key' });

// With custom options
const client = new FaosClient({
  apiKey: 'sk-your-api-key',
  baseUrl: 'https://sandbox.api.faosx.ai',
  timeout: 60000,
});

Methods

shortcut(command, task?)

Invoke an agent via shortcut command. Resolves the shortcut, then invokes the matched agent.

async shortcut(command: string, task?: string): Promise<AgentResponse>

Parameter	Type	Description
command	string	Shortcut command (e.g., "bank credit-analyst")
task	string	Optional task override. Uses resolved task_template if not provided

Returns: Promise<AgentResponse>

Throws: ShortcutNotFoundError if shortcut cannot be resolved.

const response = await client.shortcut('bank credit-analyst');
console.log(response.content);
console.log(response.agent_id);
console.log(response.metadata);

shortcutStream(command, task?)

Stream response from a shortcut agent. Returns an async iterable of string chunks.

async *shortcutStream(command: string, task?: string): AsyncIterable<string>

Parameter	Type	Description
command	string	Shortcut command (e.g., "bank credit-analyst")
task	string	Optional task override

Yields: Response chunks as string.

Throws: ShortcutNotFoundError if shortcut cannot be resolved.

for await (const chunk of client.shortcutStream('health patient-intake')) {
  process.stdout.write(chunk);
}

Properties

shortcuts

Access the underlying ShortcutsClient for lower-level operations.

client.shortcuts; // ShortcutsClient instance

Type: readonly ShortcutsClient

Complete Example

import { FaosClient, ShortcutNotFoundError } from '@faos/sdk';

const client = new FaosClient({ apiKey: 'sk-your-api-key' });

// List available shortcuts
const shortcuts = await client.shortcuts.list({ module: 'faos-bank' });
for (const s of shortcuts) {
  console.log(`  ${s.pattern}: ${s.description}`);
}

// Invoke an agent
try {
  const response = await client.shortcut('bank credit-analyst');
  console.log(`Agent: ${response.agent_id}`);
  console.log(`Response: ${response.content}`);
} catch (err) {
  if (err instanceof ShortcutNotFoundError) {
    console.log(`Not found: ${err.command}`);
    console.log(`Did you mean: ${err.suggestions.join(', ')}`);
  }
}

// Stream a response
for await (const chunk of client.shortcutStream('health patient-intake')) {
  process.stdout.write(chunk);
}