# Overview

The **GL AIP (GDP Labs AI Agents Package)** consists of three main components:

* [**`aip-agents`**](https://github.com/GDP-ADMIN/glaip-sdk/tree/main/python/aip-agents) — The underlying agent library for local execution
* [**`ai-agent-platform`**](https://github.com/GDP-ADMIN/ai-agent-platform) — The platform that provides remote server/run capabilities
* [**`glaip-sdk`**](https://github.com/GDP-ADMIN/glaip-sdk/tree/main/python/glaip-sdk) — The SDK that end users use to run agents either locally (directly via `aip-agents`) or on the remote server (via `ai-agent-platform`)
* [**`gl-sdk-cookbook`**](https://github.com/GDP-ADMIN/gl-sdk-cookbook) — A collection of self-contained, runnable examples and advanced patterns

This repository provides the SDK and CLI so you can use identical features locally, in CI, or inside your own applications.

### Architecture Overview

<figure><img src="https://2983342396-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLqsWGI0JUnaas9v07yZ5%2Fuploads%2F5banbLaZ1ajnSCKzebs1%2FScreenshot%20from%202025-12-20%2012-15-13.png?alt=media&#x26;token=0a699de7-e3a7-435c-a7d0-5f18e181df1c" alt=""><figcaption></figcaption></figure>

**Key Relationships:**

* **`glaip-sdk`** is the user-facing SDK that provides a unified interface
* **`aip-agents`** is the core agent library used by both local execution and the platform
* **`ai-agent-platform`** is the platform that wraps `aip-agents` to provide centralized management and remote execution capabilities

**Setup Requirements:**

* **Local Mode**: Configure LLM provider credentials (e.g., `OPENAI_API_KEY`) for `aip-agents` to use directly
* **Remote Mode**: Configure `AIP_API_URL` and `AIP_API_KEY` to connect to the AIP server (LLM credentials are managed by the remote server)

#### Documentation Map

Use these sections in order when exploring the SDK and CLI:

* [**Get Started**](https://gdplabs.gitbook.io/gl-aip/getting-started) — Install, configure, complete the quick start, and run curated examples.
* [**Guides**](https://gdplabs.gitbook.io/gl-aip/how-to-guides/topics) — Deep dives on lifecycle management, automation, integrations, and governance.
* [**Multi-Agent System Patterns**](https://gdplabs.gitbook.io/gl-aip/how-to-guides/multi-agent-system-patterns) — Runnable orchestration templates for complex workflows.
* [**Reference**](https://gdplabs.gitbook.io/gl-aip/resources/reference) — Definitive API, SDK, and CLI commands for implementation details.
* [**Resources**](https://gdplabs.gitbook.io/gl-aip/resources) — Changelog, glossary, and upgrade checklists.

#### Role-Based Entry Points

Choose the track that matches how you work today.

<details>

<summary>Engineers — Ship agents in applications and automation</summary>

**Why it matters:** You need reliable APIs, typed clients, and testable workflows that fit existing services.

**Start here:**

* [Quick Start Guide](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide) for first-run success.
* [Python SDK Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/python-sdk-reference) for signatures and streaming behaviour.
* [Automation & Scripting](https://gdplabs.gitbook.io/gl-aip/how-to-guides/automation-and-scripting) for CI, cron, and deployment patterns.

</details>

<details>

<summary>Product Managers — Validate agents via GLChat</summary>

**Why it matters:** You review agent behaviour for stakeholders. GLChat gives you fast access, but the CLI helps you list available agents and capture verbose output when needed.

**Start here:**

* [Quick Start Guide (CLI path)](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide/cli) — run an agent end-to-end and see detailed logs.
* [Agents guide › List & run](https://gdplabs.gitbook.io/gl-aip/how-to-guides/agents-guide#list-and-inspect-agents) — discover agent IDs/names before launching them in GLChat.
* [Automation & Scripting › Choose the right output](https://gdplabs.gitbook.io/gl-aip/how-to-guides/automation-and-scripting#choose-the-right-output-format) — switch between rich and plain responses when sharing findings.

</details>

<details>

<summary>Data Developers — Curate prompts, evaluations, and linguistic QA</summary>

**Why it matters:** You iterate on prompts, run guided evaluations, and need to inspect agent transcripts without writing code.

**Start here:**

* [Quick Start Guide](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide/cli) — follow the CLI path to validate access and run agents.
* [Configuration management guide](https://gdplabs.gitbook.io/gl-aip/how-to-guides/configuration-management-guide) — master CLI export/import loops for prompt iteration.
* [CLI Commands Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/cli-commands-reference) — look up flags for runs, exports, and transcript capture.

</details>

#### Choose Your Interface

Pick the surface that matches your environment; each summary spells out when and why to use it.

<details>

<summary>REST API — Language-agnostic integration with full control</summary>

**Why you would pick it (REST API)**

* Works with any language or infrastructure stack.
* Provides immediate access to every capability, including roadmap features as soon as they land.

**Use it when (REST API)**

* Orchestrating agents from existing services, queues, or infrastructure.
* You need custom authentication flows or to run in tightly restricted environments.

**Key docs (REST API)**

* [REST API Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/rest-api)
* [HITL REST Workflow Guide](https://gdplabs.gitbook.io/gl-aip/resources/reference/rest-api/hitl-rest-workflow-guide)
* [Security & Privacy](https://gdplabs.gitbook.io/gl-aip/how-to-guides/security-and-privacy)

</details>

<details>

<summary>Python SDK — Type-safe development and faster iteration</summary>

**Why you would pick it (Python SDK)**

* Typed client with ergonomic streaming and error handling.
* Shared utilities mirroring the CLI and test fixtures so you can reuse code between notebooks, services, and pipelines.

**Use it when (Python SDK)**

* Building Python services, workflows, or notebooks that call AIP frequently.
* You want to prototype locally, then promote the same code path into CI/CD.

**Key docs (Python SDK)**

* [Python SDK Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/python-sdk-reference)
* [Hands-On Examples](https://gdplabs.gitbook.io/gl-aip/getting-started/hands-on-examples)

</details>

<details>

<summary>CLI — Fast experiments, ops checks, and demos</summary>

**Why you would pick it (CLI)**

* Zero-code access with rich terminal rendering and JSON exports.
* Ideal for smoke-testing environments, running scheduled jobs, or supporting teams without direct code access.

**Use it when (CLI)**

* Validating connectivity or resources before automation.
* Running guided demos, QA checklists, or manual evaluations.
* Data developers iterate on prompts with export/import loops and need transcripts fast.

**Key docs (CLI)**

* [CLI Commands Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/cli-commands-reference)
* [Automation & Scripting](https://gdplabs.gitbook.io/gl-aip/how-to-guides/automation-and-scripting)

</details>

#### Platform Capabilities at a Glance

Symbols: `✅` fully supported · `🛠️` partial via customization/workarounds · `🚧` roadmap

{% hint style="info" %}
Roadmap (`🚧`) items are available via the REST API first. The SDK and CLI pick them up as soon as the corresponding clients and commands ship.
{% endhint %}

<details>

<summary>Core Operations</summary>

| Capability                        | What it covers                                                    | REST API | Python SDK | CLI |
| --------------------------------- | ----------------------------------------------------------------- | -------- | ---------- | --- |
| Agent lifecycle & metadata        | Create/list/update/delete agents with tools, MCPs, and sub-agents | ✅        | ✅          | ✅   |
| Streaming execution & artifacts   | SSE runs, file attachments, usage stats, artifact links           | ✅        | ✅          | ✅   |
| Multi-agent orchestration         | Nested agents, LangFlow imports, delegated execution patterns     | ✅        | ✅          | ✅   |
| File ingestion & chunking         | Multipart file attachments, chunk ID management, artifact reuse   | ✅        | ✅          | ✅   |
| Tool registry & uploads           | Native catalog, custom uploads, GL Connectors                     | ✅        | ✅          | ✅   |
| Memory & conversation persistence | `agent_config.memory`, chat history injection, mem0 retention     | ✅        | ✅          | 🛠️ |
| Tool output sharing controls      | Toggle `agent_config.tool_output_sharing` to share artifacts      | ✅        | ✅          | 🛠️ |

</details>

<details>

<summary>Automation &#x26; Integrations</summary>

| Capability                     | What it covers                                                   | REST API | Python SDK | CLI |
| ------------------------------ | ---------------------------------------------------------------- | -------- | ---------- | --- |
| Configuration export/import    | JSON/YAML round-tripping for agents and tools                    | ✅        | ✅          | ✅   |
| Language model routing         | `language_model_id`, provider/model fallbacks, per-run overrides | ✅        | ✅          | 🛠️ |
| MCP connectors & auth rotation | MCP CRUD, `/mcps/connect`, tool discovery                        | ✅        | ✅          | ✅   |
| MCP runtime overrides          | Per-run `runtime_config.mcp_configs` overrides                   | ✅        | ✅          | 🚧  |
| LangFlow workflow sync         | `/agents/langflow/sync` promotion of flows into agents           | ✅        | ✅          | ✅   |
| Human-in-the-loop approvals    | `/agents/hitl/*` endpoints for manual decision checkpoints       | ✅        | 🛠️        | 🛠️ |
| Run history & analytics        | `/agents/{id}/runs` pagination, status filters, usage metrics    | ✅        | 🚧         | 🚧  |
| Schedules & triggers           | `/schedules` CRUD for cron/interval/webhook automation           | ✅        | 🚧         | 🚧  |

</details>

<details>

<summary>Governance &#x26; Roadmap</summary>

| Capability              | What it covers                                            | REST API | Python SDK | CLI |
| ----------------------- | --------------------------------------------------------- | -------- | ---------- | --- |
| PII tagging & redaction | `pii_mapping` masking for inbound/outbound payloads       | ✅        | ✅          | 🚧  |
| Account lifecycle       | `/accounts` create/list/delete with master key guardrails | ✅        | 🚧         | 🚧  |
| Multi-account isolation | API-key scoped requests, master key bypass                | ✅        | ✅          | ✅   |
| RBAC role management    | Creator/Runner/Viewer roles, delegated keys               | 🚧       | 🚧         | 🚧  |

</details>

#### How It Fits Together

The SDK (`glaip-sdk`) can operate in two modes:

* **Local Mode**: Uses [`aip-agents`](https://github.com/GDP-ADMIN/glaip-sdk/tree/main/python/aip-agents) library directly on your machine, bypassing the platform.
* **Remote Mode**: Connects to the [`ai-agent-platform`](https://github.com/GDP-ADMIN/ai-agent-platform) platform via REST API. The platform's remote server uses `aip-agents` internally to execute agents.

Tokens and base URLs are shared across interfaces, so you can develop locally and promote the same configuration into CI or production with minimal changes.

* **REST API** (exposed by [`ai-agent-platform`](https://github.com/GDP-ADMIN/ai-agent-platform) platform): Every capability is implemented here first.
* **Python SDK** ([`glaip-sdk`](https://github.com/GDP-ADMIN/glaip-sdk/tree/main/python/glaip-sdk)): Wraps the API with typed models, streaming helpers, and higher-level abstractions. Can also run agents locally using [`aip-agents`](https://github.com/GDP-ADMIN/glaip-sdk/tree/main/python/aip-agents).
* **CLI**: Uses the SDK under the hood so operations and demos mirror production behaviour.

#### Low-Code Philosophy

The SDK emphasizes declarative patterns for building agents with minimal code:

```python
# Create and run an agent
from glaip_sdk import Agent

agent = Agent(name="hello", instruction="You are helpful")
response = agent.run("Hello!")
```

**Key principles:**

* **Agent/Tool/MCP as primary abstractions** — Work directly with high-level classes
* **Environment-based defaults** — Credentials read from `AIP_API_URL` and `AIP_API_KEY`
* **Progressive complexity** — Simple patterns for simple tasks, advanced patterns available
* **Agent-first with client as secondary** — Use the Agent pattern for most workflows; keep client APIs for listing, batch operations, and legacy code paths

#### Start Building

Ready to go from prototype to production? Follow this path to ship quickly:

1. **Install & configure** — Set up credentials and the CLI with [Install & Configure](https://gdplabs.gitbook.io/gl-aip/getting-started/install-and-configure).
2. **Run the quick start** — Use the Agent-first pattern (recommended), with the client pattern available as a secondary option in the [Quick Start Guide](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide) to create and run your first agent.
3. **Explore patterns** — Use the [Hands-on Examples](https://gdplabs.gitbook.io/gl-aip/getting-started/hands-on-examples) to pick the right pattern (single agent, multi-agent, class pattern, runtime config, local execution, report automation).
4. **Iterate on prompts** — Use the CLI export/import loop in [Configuration management](https://gdplabs.gitbook.io/gl-aip/how-to-guides/configuration-management-guide) to refine instructions safely.
5. **Add real workflows** — Explore [Tools](https://gdplabs.gitbook.io/gl-aip/how-to-guides/tools-guide), [File processing](https://gdplabs.gitbook.io/gl-aip/how-to-guides/file-processing-guide), or [Multi-agent patterns](https://gdplabs.gitbook.io/gl-aip/how-to-guides/multi-agent-system-patterns) as you expand capabilities.

The GL AIP package, SDK, and CLI give you a single, consistent toolkit to build, test, and operate AI agents anywhere.