# 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
**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.
Engineers — Ship agents in applications and automation
**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.
Product Managers — Validate agents via GLChat
**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.
Data Developers — Curate prompts, evaluations, and linguistic QA
**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.
#### Choose Your Interface
Pick the surface that matches your environment; each summary spells out when and why to use it.
REST API — Language-agnostic integration with full control
**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)
Python SDK — Type-safe development and faster iteration
**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)
CLI — Fast experiments, ops checks, and demos
**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)
#### 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 %}
Core Operations
| 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 | ✅ | ✅ | 🛠️ |
Automation & Integrations
| 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 | ✅ | 🚧 | 🚧 |
Governance & Roadmap
| 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 | 🚧 | 🚧 | 🚧 |
#### 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://gdplabs.gitbook.io/gl-aip/overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
