SDK Overview

The Flow SDK (flow-sdk) is the official Python SDK for the Manifest Platform. Inside Code Blocks, Hosted Services, Agents, and Workflows, the SDK is pre-installed and auto-configured — just import and start building.

from flow_sdk import FlowSDK

flow = FlowSDK()  # auto-configured inside platform runtimes

Developer Tools Coming Soon

The flow-sdk CLI and local developer tools are not yet publicly available. They will be released in an upcoming release. Today, the SDK is available inside all Manifest Platform runtimes — no installation required.

Architecture

The SDK is organized into four clients, each designed for a specific context:

flowchart TD
    subgraph dev ["Developer Machine"]
        CLI["flow-sdk CLI"] --> CLIClient
    end

    subgraph scripts ["Scripts & Notebooks"]
        GatewayClient
        PlatformClient
    end

    subgraph svc ["Running Service / Code Block"]
        FlowSDK
        subgraph ns ["Namespaces"]
            direction LR
            GW_NS["gateway"]
            DS_NS["datasets"]
            CB_NS["code_blocks"]
            AG_NS["agents"]
            WF_NS["workflows"]
            SVC_NS["services"]
            ST_NS["state"]
            SEC_NS["secrets"]
        end
        FlowSDK --> ns
    end

    subgraph platform ["Manifest Platform"]
        direction LR
        API["Platform API"]
        Gateway["AI Gateway"]
        API --> HSL["Hosted Services"]
        API --> Exec["Execution Engine"]
    end

    CLIClient -->|"Sync HTTP"| API
    FlowSDK -->|"Async HTTP"| API
    FlowSDK -->|"Async HTTP"| Gateway
    GatewayClient -->|"Async HTTP"| Gateway
    PlatformClient -->|"Async HTTP"| API

When to Use Which Client

The SDK provides four distinct clients. Choose the one that matches your use case:

Client	Sync/Async	Use Case	Authentication	Availability
FlowSDK	Async	Code inside hosted services and code blocks	Auto-configured from environment	Available now
CLIClient	Sync	Invoking deployed services from scripts	~/.flow/config.json credentials	Coming soon
GatewayClient	Async	Direct AI Gateway access (chat, embeddings)	JWT token or environment variable	Coming soon
PlatformClient	Async	Low-level platform API calls	JWT token or environment variable	Coming soon

Decision Guide

flowchart TD
    A["Where is your code running?"] --> B{"Inside a hosted service\nor code block?"}
    B -->|Yes| C["Use FlowSDK"]
    B -->|No| D{"Need AI model\ninference only?"}
    D -->|Yes| E["Use GatewayClient"]
    D -->|No| F{"CLI script or\nautomation?"}
    F -->|Yes| G["Use CLIClient"]
    F -->|No| H["Use PlatformClient"]

Start with FlowSDK

If you are writing code that runs on the platform (hosted services, code blocks, agents, workflows), FlowSDK is almost always the right choice. It auto-configures from the execution environment and exposes every platform capability through typed namespaces.

Quick Start

FlowSDK (Hosted Services)CLIClient (Scripts)CLI

from flow_sdk import FlowSDK

flow = FlowSDK()  # auto-configures from environment

# Call the AI Gateway
response = await flow.gateway.chat_completion(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Summarize this document."}],
)

# Query a dataset
rows = await flow.datasets.query(
    "my-dataset",
    {"fields": ["name", "email"], "limit": 100},
)

Coming Soon

CLIClient will be available publicly in an upcoming release.

from flow_sdk.config import load_config
from flow_sdk.cli_client import CLIClient

config = load_config()  # reads ~/.flow/config.json
client = CLIClient(config)

result = client.invoke_service(
    service_id="<service-uuid>",
    method="POST",
    path="/analyze",
    body={"text": "Hello, world!"},
)
print(result)

Coming Soon

The flow-sdk CLI will be available publicly in an upcoming release.

# Authenticate
flow-sdk login --api-key fl_your_key --url https://api.flow.marut.cloud

# Scaffold a new component
flow-sdk scaffold my-agent --template agent

# Deploy to the dev ring
flow-sdk deploy ./my-agent --ring dev

Package Exports

The flow-sdk package exports the following top-level symbols:

from flow_sdk import (
    # Main SDK facade
    FlowSDK,
    FlowSDKError,

    # Platform client (async, low-level)
    PlatformClient,
    PlatformClientError,
    PlatformAuthenticationError,
    PlatformPermissionError,
    PlatformNotFoundError,
    PlatformExecutionError,

    # Gateway client (async, AI inference)
    GatewayClient,
    GatewayClientError,
    GatewayAuthError,
    GatewayRateLimitError,
    GatewayModelNotFoundError,
    GatewayProviderError,

    # Component framework
    BaseComponent,
    ComponentRunner,
    RuntimeContext,

    # Secrets and state
    SecretsClient,
    StateClient,
)

Next Steps

• FlowSDK — The main SDK facade for hosted services and code blocks
• Examples — Cookbook of common patterns and recipes
• CLIClient — Invoke deployed services from scripts (coming soon)
• CLI Commands — login, scaffold, deploy, publish, and more (coming soon)
• GatewayClient — Direct AI Gateway access (coming soon)
• PlatformClient — Low-level platform API client (coming soon)