FaosClient

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

from faos import FaosClient

Constructor

FaosClient(api_key: str, base_url: str = "https://api.faosx.ai")

Parameter	Type	Default	Description
api_key	str	required	FAOS API key for authentication
base_url	str	"https://api.faosx.ai"	API base URL

Example

client = FaosClient(api_key="sk-your-api-key")

# Or with custom base URL
client = FaosClient(
    api_key="sk-your-api-key",
    base_url="https://sandbox.api.faosx.ai"
)

Methods

shortcut(command, task=None)

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

async def shortcut(self, command: str, task: str | None = None) -> AgentResponse

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

Returns: AgentResponse

Raises: ShortcutNotFoundError if shortcut cannot be resolved.

response = await client.shortcut("bank credit-analyst")
print(response.content)
print(response.agent_id)
print(response.metadata)

shortcut_stream(command, task=None)

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

async def shortcut_stream(
    self, command: str, task: str | None = None
) -> AsyncIterator[str]

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

Yields: Response chunks as str.

Raises: ShortcutNotFoundError if shortcut cannot be resolved.

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

close()

Close the underlying HTTP client. Should be called when done using the client.

async def close(self) -> None

await client.close()

Context Manager

FaosClient supports async context manager protocol for automatic cleanup:

async with FaosClient(api_key="sk-...") as client:
    response = await client.shortcut("bank credit-analyst")
    print(response.content)
# Client is automatically closed

Properties

shortcuts

Access the underlying ShortcutsClient for lower-level operations.

client.shortcuts  # ShortcutsClient instance

Complete Example

import asyncio
from faos import FaosClient, ShortcutNotFoundError

async def main():
    async with FaosClient(api_key="sk-your-api-key") as client:
        # List available shortcuts
        shortcuts = await client.shortcuts.list(module="faos-bank")
        for s in shortcuts:
            print(f"  {s.pattern}: {s.description}")

        # Invoke an agent
        try:
            response = await client.shortcut("bank credit-analyst")
            print(f"Agent: {response.agent_id}")
            print(f"Response: {response.content}")
        except ShortcutNotFoundError as e:
            print(f"Not found: {e.command}")
            print(f"Did you mean: {e.suggestions}")

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

asyncio.run(main())