search

downloadInstall and Configure

Comprehensive setup guide for the AIP SDK with advanced configuration options, security best practices, and troubleshooting tips.

circle-info

Need the fastest path to a working agent? Jump to the Quick Startarrow-up-right first, then return here when you need deeper configuration.

hashtag
Requirements

  • Python 3.11 or 3.12 (3.10 and earlier are not supported)

  • Operating System: Windows, macOS, or Linux

  • Network: Internet access for package installation

circle-info

Corporate networks may require outbound proxy variables (e.g. HTTP_PROXY/HTTPS_PROXY). Set those before installing or running the CLI if your organisation routes traffic through a proxy.

hashtag
Install SDK and CLI Together

Installing glaip-sdk provides both the Python SDK and the aip CLI. Pick the install command that matches how you manage dependencies.

circle-info

Local Execution Mode: To run agents locally using the aip-agents library, install the [local] extra:

pip install --upgrade "glaip-sdk[local]"

This includes aip-agents for local LLM execution. See Local vs Remote Modearrow-up-right for when to use each mode.

circle-exclamation

Privacy Features: If you plan to use PII masking and privacy features, install glaip-sdk[privacy]:

pip install --upgrade "glaip-sdk[privacy]"

Note: Privacy features work in both remote and local modes. For local execution with privacy, use glaip-sdk[local,privacy]. See the Security and Privacy guidearrow-up-right for more details.

pip (Linux/macOS)

# Standard installation
pip install --upgrade glaip-sdk

# With local execution support
pip install --upgrade "glaip-sdk[local]"

Use when you manage environments with venv or system Python. Activate the environment before running the command.

pip (Windows PowerShell)

Run inside an elevated PowerShell session if your organisation restricts installs. Use py -m pip install --upgrade glaip-sdk when pip is not on PATH.

Poetry (project managed)

Ideal when the SDK ships with your application code. poetry run ensures the CLI uses the project virtual environment.

uv tool

Great for users who prefer reproducible global installs while keeping Python projects isolated.

pipx (CLI only)

Deploys the CLI in an isolated environment and keeps your global Python clean. Ideal for operations or QA stations. Recommended for data developers who only need the CLI.

  • --upgrade (or the equivalent) ensures you pick up the latest release or refresh an existing installation.

  • Using a virtual environment? Activate it first, then run the same command.

  • Verify the CLI once installed:

circle-info

If pip is not available as a command, fall back to python3 -m pip (Linux/ macOS) or py -m pip (Windows). After installing, ensure ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Python311\Scripts (Windows) is on your PATH so aip resolves.

hashtag
Configure Access Options

You only need these settings when pointing the SDK or CLI to the AIP server. Local runs (using aip-agents directly) use the built-in defaults. Choose the option that matches your workflow; each method sets the same API URL and API key, so pick one.

.env file (project scoped)

  1. Create a .env file alongside your project code:

  2. Load it with python-dotenv, your framework of choice, or a task runner.

  3. Ideal when you check environment files into a secure secrets store per project.

Shell profile (persistent)

Use when you want the SDK and CLI available in every terminal.

  • Linux / macOS:

    Add the lines to ~/.bashrc, ~/.zshrc, or your shell profile to persist them.

  • Windows PowerShell:

    Restart the terminal after running setx so the variables are picked up.

Interactive CLI (per machine)

Run the built-in helper to store credentials in the CLI config file:

You will be prompted for:

  • API URL

  • API Key

This is convenient on developer laptops or CI agents that already store the values securely.

circle-info

Configuration precedence: CLI config (aip configure) > shell environment variables > .env file > library defaults.

circle-info

CLI configuration is stored in ~/.aip/config.yaml (Linux/macOS) or %USERPROFILE%\\.aip\\config.yaml (Windows).

hashtag
Verify Installation

Confirm both the CLI and SDK can reach your AIP instance.

Expected output includes ✅ Connected to AIP server.

circle-exclamation

aip status may also report:

Indicator
Meaning
Common fix

⚠️ Partial Connection

DNS/SSL failure or blocked outbound request after the client connects.

Check VPN/proxy settings, verify AIP_API_URL, and retry from a network with internet access.

❌ Connection failed

Credentials missing or rejected before any data flows.

Re-run aip configure or export AIP_API_KEY/AIP_API_URL, then rerun the command.

Timed out

CLI could not reach the API within the configured timeout.

Confirm the service is up and adjust --timeout if your environment requires longer waits.

circle-exclamation

If the error mentions Temporary failure in name resolution, your DNS cannot resolve the host—double-check the URL or try again once network connectivity is restored.

hashtag
Security Best Practices

These apply to anyone handling API keys for the platform—whether you are a developer, DevOps engineer, or administrator.

  • Use different API keys per environment (development, staging, production).

  • Never commit keys to source control—prefer secret managers or CI variables.

  • Rotate keys regularly and revoke unused ones promptly.

hashtag
Optional CLI Configuration Helpers

Use these after installation when you need to inspect or adjust saved values.

hashtag
Continue

Ready to run your first agent? Head to the Quick Startarrow-up-right and follow the Python or CLI track.

PreviousNavigationNextQuick Start Guide

Last updated