SDK Getting Started

Build your first FAOS integration in 5 minutes. This tutorial walks through installation, authentication, and invoking your first agent.

Duration: 5 minutes | Difficulty: Beginner

Prerequisites

• FAOS account with API key (get one at app.faosx.ai)
• Python 3.10+ or Node.js 18+

Step 1: Install the SDK

Python

pip install faos

TypeScript

npm install @faos/sdk

Step 2: Set Your API Key

Store your API key as an environment variable:

Linux / macOS

export FAOS_API_KEY="sk-your-api-key-here"

Windows

$env:FAOS_API_KEY = "sk-your-api-key-here"

Never hardcode API keys

Always use environment variables or a secrets manager. Never commit keys to version control.

Step 3: Create a Client

Python

import os
from faos import FaosClient

client = FaosClient(api_key=os.environ["FAOS_API_KEY"])

TypeScript

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

const client = new FaosClient({
  apiKey: process.env.FAOS_API_KEY!,
});

Step 4: Invoke an Agent

Use a shortcut command to invoke an agent. Shortcuts follow the pattern <module> <agent>:

Python

import asyncio

async def main():
    async with FaosClient(api_key=os.environ["FAOS_API_KEY"]) as client:
        # Invoke the Banking Credit Analyst
        response = await client.shortcut("bank credit-analyst")
        print(response.content)

asyncio.run(main())

TypeScript

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

Step 5: Explore Available Shortcuts

List what agents are available in a module:

Python

shortcuts = await client.shortcuts.list(module="faos-bank")
for s in shortcuts:
    print(f"{s.pattern}: {s.description}")

TypeScript

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

Step 6: Stream Responses

For real-time output, use streaming:

Python

async for chunk in client.shortcut_stream("health patient-intake"):
    print(chunk, end="", flush=True)

TypeScript

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

Step 7: Handle Errors

Python

from faos import ShortcutNotFoundError, ShortcutRateLimitError

try:
    response = await client.shortcut("unknown agent")
except ShortcutNotFoundError as e:
    print(f"Not found: {e.command}")
    print(f"Suggestions: {e.suggestions}")
except ShortcutRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

TypeScript

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

try {
  await client.shortcut('unknown agent');
} catch (err) {
  if (err instanceof ShortcutNotFoundError) {
    console.log(`Not found: ${err.command}`);
    console.log(`Suggestions: ${err.suggestions}`);
  } else if (err instanceof ShortcutRateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  }
}

What's Next?

• Shortcut System Guide -- Deep dive into the shortcut system
• Industry Module Guides -- Explore all 21 industry verticals
• Banking Tutorial -- Hands-on banking agents walkthrough
• Python SDK Reference -- Full Python API docs
• TypeScript SDK Reference -- Full TypeScript API docs