SDK Overview

FAOS provides official SDKs for Python and TypeScript/JavaScript, enabling programmatic access to the FAOS platform from your applications.

Installation

Python

pip install faos

Requirements: Python 3.10+

TypeScript / JavaScript

npm install @faos/sdk
# or
yarn add @faos/sdk

Requirements: Node.js 18+

Quick Example

Python

from faos import FaosClient

async def main():
    client = FaosClient(api_key="sk-...")

    # Invoke an agent via shortcut
    response = await client.shortcut("bank credit-analyst")
    print(response.content)

    # Stream a response
    async for chunk in client.shortcut_stream("health patient-intake"):
        print(chunk, end="")

    await client.close()

TypeScript

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

const client = new FaosClient({ apiKey: 'sk-...' });

// Invoke an agent via shortcut
const response = await client.shortcut('bank credit-analyst');
console.log(response.content);

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

Key Concepts

Shortcuts

Shortcuts are the primary way to invoke agents. A shortcut command like "bank credit-analyst" resolves to the appropriate agent in the Banking module.

<module> <agent>

• Module: Industry vertical (e.g., bank, health, mfg)
• Agent: Specialist within that module (e.g., credit-analyst, patient-intake)

Agent Response

Every agent invocation returns an AgentResponse containing:

Field	Type	Description
content	string	The agent's response text
agent_id	string	ID of the agent that responded
metadata	object	Additional response metadata

Error Handling

Both SDKs provide typed error classes:

Error	When
ShortcutNotFoundError	Shortcut command cannot be resolved
ShortcutRateLimitError	API rate limit exceeded
FaosError	Base error for all SDK errors

SDK Architecture

FaosClient
├── shortcut(command)        → AgentResponse
├── shortcut_stream(command) → AsyncIterator<string>
└── shortcuts                → ShortcutsClient
    ├── resolve(command)     → ShortcutResolution
    └── list(options?)       → ShortcutDefinition[]

Next Steps

• Python SDK Reference -- Full Python API reference
• TypeScript SDK Reference -- Full TypeScript API reference
• Getting Started Guide -- Setup and first steps
• Authentication -- API key and OAuth setup