SDK Integration Model
1. Purpose
The Site Application must support both lower-level model/client SDK integration and higher-level agent SDK integration. These are related but they solve different problems and should not be treated as interchangeable.
2. Model / Client SDK
A model or client SDK is the direct programming interface to an AI provider or model service. It is appropriate when the Site implementation wants to own most runtime behavior itself.
Typical responsibilities retained by the Site implementation include:
- request construction and model invocation;
- conversation-state handling;
- tool-dispatch logic;
- retries and timeout behavior;
- structured-output validation;
- prompt assembly;
- streaming behavior;
- error handling;
- telemetry and correlation;
- application-specific orchestration.
flowchart TD
S(["Site Feature"]):::actor --> C[["Model / Client SDK"]]:::process
C --> P[["Model Provider"]]:::model
P --> R["Model Response"]:::model
R --> O[("Site-owned orchestration / state")]:::store
classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
Use this mode when the requirement is primarily model access, not autonomous or agentic execution.
3. Agent SDK
An agent SDK provides a runtime abstraction above direct model calls. Depending on the chosen SDK, it may manage:
- agent instructions;
- model calls;
- tool selection and invocation;
- multi-turn execution loops;
- handoffs between agents;
- session state;
- guardrails;
- tracing;
- human approval steps;
- structured results;
- long-running execution integration.
flowchart TD
G(["Goal / Task"]):::actor --> A[["Agent Runtime"]]:::model
A --> M[["Model"]]:::model
A --> T["Tools"]:::process
A --> K[("Knowledge")]:::store
A --> O[["Other Agents"]]:::model
M --> R["Observe / Reason / Continue"]:::model
T --> R
K --> R
O --> R
R --> X(["Result"]):::output
classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220
4. Client SDK vs Agent SDK
| Concern | Model / Client SDK | Agent SDK |
|---|---|---|
| Primary purpose | Direct model/API integration | Goal-oriented agent execution |
| Execution loop | Site code owns it | Agent runtime can own it |
| Tool dispatch | Site code | Runtime-assisted or runtime-managed |
| Session state | Site-managed | Often built into or integrated with runtime |
| Handoffs | Custom | Common agent-runtime feature |
| Guardrails | Custom | Often first-class |
| Workflow planning | Custom | Often supported |
| Best fit | Assistant, embedded AI feature, controlled inference | Agent and autonomous scenarios |
5. Sandbox Clarification
A sandbox is not a universal requirement for every agent SDK.
Sandboxed execution becomes important when an agent is allowed to execute untrusted or generated code, manipulate files, run shell commands, browse external resources, or perform other high-risk operations. The sandbox is therefore an execution-isolation capability, not the definition of an agent.
Recommended rule:
flowchart TD
A[["Agent execution"]]:::model --> R{"Execution profile"}:::gate
R -->|"Bounded approved APIs / tools"| N(["Sandbox may not be required"]):::output
R -->|"Generated code / shell / file workspace"| S(["Use isolated sandbox"]):::govern
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220
classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220
The sandbox policy must be selected from the capabilities exposed to the agent rather than from the label "Agent SDK" alone.
6. Direct Code and Low-Code Modes
The Site Application should support two implementation modes.
6.1 Direct Code
Direct code integration is appropriate when the Site requires:
- complete control over orchestration;
- custom tool contracts;
- proprietary execution logic;
- complex observability;
- custom state handling;
- deployment without dependency on a visual flow editor.
Supported implementation languages should be defined by the package or component. TypeScript/JavaScript and Python are common choices, but the platform model should not hard-code one language.
6.2 Low-Code / Visual Orchestration
Visual systems such as Flowise can be used when users need to define AI flows graphically. This is an implementation option, not the canonical definition of the agent itself.
flowchart TD
D[("Site Agent Definition")]:::store --> C[["Code Implementation"]]:::process
D --> F[["Flowise / Visual Implementation"]]:::process
D --> E[["External Agent Service"]]:::external
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3
The registry should therefore reference an implementation type rather than make the flow editor the system of record for the business meaning of the agent.
7. Packaging Model
A reusable SDK integration should be represented through package configuration rather than hard-coded application configuration.
Recommended configuration groups:
| Group | Examples |
|---|---|
| Provider | OpenAI-compatible, Azure-hosted, Gemini-compatible, local runtime |
| Endpoint | Base URL / deployment URL |
| Authentication | Secret reference, managed identity, OAuth, API key |
| Model | Model/deployment identifier |
| Runtime | Client SDK / Agent SDK / custom runtime |
| Network | Proxy, TLS, internal/external zone |
| Limits | Timeout, rate limit, token/output limits |
| Observability | Trace exporter, correlation policy |
| Policy | Tool allow-list, data classification, approval rules |
Secrets must be stored through the approved secret/connection mechanism and referenced by identifier.
8. Recommended Runtime Selection
flowchart TD
N{"Need AI capability?"}:::gate
N -->|"Direct completion / chat / extraction"| C[["Model / Client SDK"]]:::model
N -->|"Tools + iterative goal execution"| A[["Agent SDK or custom agent runtime"]]:::model
N -->|"Fixed deterministic sequence"| W[["Automation engine"]]:::process
N -->|"Visual AI orchestration"| F[["Flowise or equivalent"]]:::process
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220