GDP Labs AI Stack Field Guide

A concise map of the moving pieces: GL SDK / GLAIP, GLAIR Connectors, and CATAPA Digital Employee.

1. Ecosystem map

flowchart TB
    subgraph GL["GL SDK / GLAIP"]
        A["Agent runtime<br/>LLM calls, memory, streaming<br/>PII masking, tracing"]
    end

    subgraph CATAPA_SDK["CATAPA SDK"]
        C["catapa<br/>Public CATAPA API"]
        CP["catapa_private<br/>Internal CATAPA API"]
    end

    subgraph CONN_SDK["GL Connectors SDK / Tools"]
        CS["gl_connectors_sdk<br/>Direct connector API"]
        CT["gl_connectors_tools<br/>Skill factory + MCPs"]
    end

    subgraph CONN_HOST["GLAIR Connectors host"]
        H1["connectors.glair.ai<br/>Public API"]
        H2["connectors.gdplabs.id<br/>Internal runtime"]
        CON["Connectors Console"]
    end

    subgraph DE["CATAPA Digital Employee"]
        D["LangChain/LangGraph agents<br/>tools + MCPs"]
    end

    A -->|calls| C
    A -->|calls| CP
    A -->|forwards| CS
    A -->|uses| CT
    CS -->|REST| H1
    CS -->|REST| H2
    CT -->|installs skills/MCPs| H2
    A -->|gl_connectors_token| D
    D -->|catapa SDK| C
    D -->|catapa_private SDK| CP
    D -->|sync connector methods| CS
    H1 -->|OAuth callback| D
    H2 -->|MCP server| D
    CON -->|configure integrations| H1
    CON -->|configure integrations| H2

Everything in the diagram is connected, but the arrow style matters:

Solid arrows = direct code/API dependencies.
Labeled arrows = token propagation or runtime wiring.
GLAIP can talk to CATAPA data, GL Connectors API, and GL Connectors MCP servers.
A Digital Employee reuses the same SDKs and connector runtime, but adds its own agent topology and CATAPA-specific guardrails.

2. GL SDK / GLAIP

GL SDK = GDP Labs Software Development Kit. GLAIP = the agent-interaction layer (SDK + runtime).

Key packages:

Package	What it does
`glaip-sdk`	Agent runtime, `Agent`, `run_agent`, streaming, `runtime_config`, `trace`, `MCP`
`gl-connectors-sdk`	Direct connector API fluent interface
`gl-connectors-tools` / `gl-connectors-tools-binary`	Skill factory, install skills from GitHub
`catapa`	Public CATAPA API SDK
`catapa_private`	Internal/private CATAPA API SDK

Common AIP patterns:

from glaip_sdk import Agent, MCP

agent = Agent(
    name="github-agent",
    instruction="Summarise PRs",
    mcps=[MCP.from_native("github")],
    mcp_configs={"github": {"allowed_tools": ["github_list_pull_requests"]}},
)

Token propagation for connector auth:

client.run_agent(
    agent_id="...",
    message="...",
    gl_connectors_token="<user-token>",
)

gl_connectors_token is forwarded to /agents/{agent_id}/run and used for GL Connectors pre-checks.
During local make run it may not reach custom tools; add env fallback (GL_CONNECTORS_TOKEN) in the tool.

3. GLAIR Connectors

GLAIR Connectors is an OAuth gateway and tool catalog for external services (Google, GitHub, Slack, SQL, etc.).

Three ways to use it

Use when	Approach
One precise external operation	Direct API (`gl_connectors_sdk`)
Agent needs broad/uncertain access to a service	MCP server with `allowed_tools`
Repeatable workflow, formatting, rules	Agent Skill

API surface (admin/registry)

Base URLs:

https://connectors.glair.ai — common public API
https://connectors.gdplabs.id — internal/GL ecosystem runtime
Console: https://connectors.glair.ai/console

Main endpoints:

POST /clients — create client (API key holder)
GET /clients, PATCH /clients — list / update
POST /users — create user
POST /auth/tokens — login, get user token
DELETE /auth/tokens — logout
GET /users/me
GET /connectors/{name}/auth-schema — auth config shape
POST /connectors/{name}/integrations — create integration
GET|POST|DELETE /connectors/{name}/integrations/{user_identifier}
GET /connectors/{name}/success-authorize-callback — OAuth callback
GET /catalog/mcp — list MCP servers
GET /catalog/tools — list native tools
GET /skills/list — curated skills registry
GET /skills/openclaw — UGC skills
GET /api/skills — skill details list
POST /api/skills — register a new skill
POST /api/skills/tenants — attach skill to tenant
GET /api/skills/tenants/{client_id}
PUT|GET|DELETE /api/skills/{skill_id}

SDK fluent shape

from gl_connectors_sdk.connector import GLConnectors

connector = GLConnectors(
    api_base_url="https://connectors.glair.ai",
    api_key=client_key,
)

response = (
    connector.connect("google_drive")
    .action("search_files")
    .params({"query": "name contains 'wfo'"})
    .token(user_token)
    .run()
)

MCP server pattern

https://connectors.gdplabs.id/<connector>/mcp

Examples:

GitHub: https://connectors.gdplabs.id/github/mcp
Google Mail: https://connectors.gdplabs.id/google_mail/mcp
Slack: https://connectors.gdplabs.id/slack/mcp

Auth: X-Api-Key header for client, Authorization: Bearer <user-token> for user. Optional X-Integration to pick a specific integration.

Always restrict tools:

mcp_configs={
    "github": {"allowed_tools": ["github_list_pull_requests"]}
}

4. CATAPA Digital Employee

A Digital Employee (DE) is an LLM-driven agent inside CATAPA that answers domain-specific requests and performs workflows.

Topology

Single agent: one domain, few tools, no specialist boundary.
Coordinator + sub-agents: multiple specialists, different tools per responsibility, coordinator routes work.

Default: prefer single agent unless multi-agent clearly reduces risk.

Build workflow (de-build-de-catapa)

Source of truth repo: https://github.com/GDP-ADMIN/prompt-template/tree/main/project-wide/digital-employee

Steps:

Prepare PRD.
Read de-build-de-catapa/README.md and AGENTS.md.
Fill <REPLACE: ...> placeholders in step prompts.
step-1-scaffolding.sh
step-2-architecture-specification.md
Review architecture (tools, MCPs, sub-agents, missing/unnecessary parts).
step-3-implementation-specification.md
Review spec (no invented endpoints, no invented query syntax, clear env vars, good errors).
step-4-implementation.md
Configure .env.
make run MESSAGE="...".
step-5-validation-and-compliance.md.
step-6-integration-test-verification.md (live tests when feasible).

Prompt templates

prompt-template-single-agent-instructions.md
prompt-template-multi-agent-coordinator-instructions.md
prompt-template-multi-agent-subagent-instructions.md

These are instruction scaffolding, not runtime code.

CATAPA SDK notes

Public import:

from catapa import Catapa

Private/internal import:

from catapa_private import CatapaPrivate

SDK version: minimum >=0.3.3; TMO pins 0.3.6. Pin to latest compatible per DE.

Querying CATAPA API

Use RSQL ?filter=:

?filter=companyId==zfrl;status==active
?filter=employeeId=in=(123,456)
?filter=createdAt=gt=2025-01-01

Operators: ==, =in=, =gt=, =ge=, =lt=, =le=, =contains=. Combine with ; (AND) or , (OR within same field).

Legacy ?query= with : / > / < / , is deprecated and overloaded; avoid in new code.

Pagination: default size is small; use up to 50 per page from CATAPA-API OpenAPI spec. TMO uses internal RECAPITULATION_DETAIL_PAGE_SIZE = 400 for its own batching.

Guardrails

Never guess CATAPA endpoints or query params.
Enforce tenant isolation.
No raw PII in logs/output.
No logger.info() on raw result objects.
Use HITL for risky writes.
Register MCPs per-agent, not globally.
Prefer built-in tools/MCPs over custom code.
Keep business reasoning in prompts/instructions, not tool/client code.

5. Integration patterns

When to use what

Need	Use
Single deterministic external call	`gl_connectors_sdk` API
Agent chooses among many service actions	MCP server with `allowed_tools`
Repeatable format/checklist/workflow	Agent Skill
CATAPA HRIS data	`catapa` / `catapa_private` SDK
Live CATAPA action	CATAPA SDK + correct tenant/user

Export + notification pattern

For Excel/PDF artifacts + email:

Generate artifact, upload to object storage, get presigned URL.
Call google_mail sync method inside LangChain _run (async fails inside running event loop).
Build email body in tool with _format_email_body() so markdown table/sections survive LLM collapse.
Use real presigned URL; never leave placeholder variables.

Verifying sent email

Use gogcli (gog gmail get/search) rather than browser automation. Faster and authoritative.

6. Quick command cheat sheet

# Run a DE locally
make run MESSAGE="Run lateness frequency analysis for Finance last month"

# GL Connectors SDK install
uv add gl-connectors-sdk

# GL Connectors tools/skill install
uv add gl-connectors-tools-binary

# AIP SDK install
uv add glaip-sdk

# CATAPA SDK
uv add catapa catapa-private

# GitHub prompt-template source
gh api repos/GDP-ADMIN/prompt-template/contents/project-wide/digital-employee/de-build-de-catapa/README.md

7. Source-of-truth links

Topic	Location
GL SDK docs	`/llms-full.txt` on SDK GitBook
GL Connectors API spec	`/tmp/glair-openapi.json` (or `connectors.glair.ai/openapi.json`)
GL Connectors SDK usage	`skill_view:glair-connectors`
GL Connectors HTTP endpoints	`skill_view:glair-connectors-api`
CATAPA DE GitBook	`https://gdplabs.gitbook.io/catapa/developer-documentation/digital-employee/`
CATAPA DE GitBook markdown trick	append `.md` to page URL
CATAPA DE build prompts	`https://github.com/GDP-ADMIN/prompt-template/tree/main/project-wide/digital-employee`
CATAPA DE repo	`~/Documents/github/CATAPA/digital-employee/main`
CATAPA API/OpenAPI	`~/Documents/github/CATAPA/CATAPA-API`
CATAPA SDK	`~/Documents/github/CATAPA/CATAPA-SDK`

Last updated: 2026-07-02. If a link breaks, prefer the local CATAPA clone or the SDK GitBook /llms-full.txt over web search snippets.

jamesjfoong/gdp-ai-stack-field-guide.md

Select an option

No results found