# Adaline Integration

> High-level guide for integrating your AI application with Adaline. Use when starting a new Adaline integration, choosing between API/SDK approaches, or planning which Adaline features to adopt.

- Skill: `adaline/adaline-integration` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add adaline/adaline-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adaline/adaline-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: adaline (https://skillmd.com/u/adaline)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/adaline/adaline-integration

---


# Adaline Integration Guide

## What is Adaline

Adaline is the single platform to instrument, improve, define behaviors for, monitor, prompt, evaluate, and administer AI agents. It solves the AI Development Lifecycle (ADLC) — the end-to-end process of building, testing, shipping, and operating AI-powered applications.

Core pillars:

- **Instrument** — send logs (traces and spans) from your application so every LLM call, tool execution, and retrieval step is captured
- **Monitor** — analyze quality, latency, cost, and error rates across your AI operations in the Adaline dashboard
- **Prompt** — build and test prompts in the playground, deploy prompt snapshots to environments, and fetch approved snapshots at runtime
- **Evaluate** — run prompts against datasets at scale using rule-based and LLM-as-judge evaluators to gate quality before shipping
- **Improve** — optimize prompts, generate synthetic datasets, and create auto evaluators from product signals
- **Behaviors** — discover semantic patterns and behavior maps from production data

## Configuration

Set these environment variables when your Adaline credentials are available:
- `ADALINE_API_KEY` — your workspace API key (from Settings > API Keys at app.adaline.ai)
- `projectId` — your project ID (from the dashboard sidebar)
- Base URL for all REST calls: `https://api.adaline.ai/v2`

You can start integrating before you have credentials. All code examples use placeholder values — replace them with real values when ready.

## Integration Decision Tree

Choose the right skill based on your goal:

| Your goal | Skill to use | Approach |
|-----------|-------------|----------|
| Send traces/spans from your app | adaline-logs | SDK (TS/Python) or REST API |
| Fetch deployed prompts at runtime | adaline-deployments | SDK or REST API |
| Create/manage prompts programmatically | adaline-prompts | REST API |
| Build evaluation datasets | adaline-datasets | REST API |
| Set up quality evaluators | adaline-evaluators | REST API |
| Run evaluations at scale | adaline-evaluations | REST API |
| Check available AI providers/models | adaline-providers | REST API |

## Choosing Your Approach

### TypeScript SDK (@adaline/client)

Best for: Node.js and TypeScript applications. Provides typed namespace clients for the public API, helpers for deployed prompts, and buffered trace/span logging.

Install: `npm install @adaline/client @adaline/api`

Use for: logging, deployment fetching, and typed management operations for datasets, prompts, evaluators, evaluations, providers, models, projects, and logs.

### Python SDK (adaline-client)

Best for: Python applications. The current Python SDK is async-first: API calls and `monitor.flush()` are awaited inside an asyncio event loop.

Install: `pip install adaline-client adaline-api`

Use for: logging, deployment fetching, and typed management operations for datasets, prompts, evaluators, evaluations, providers, models, projects, and logs.

### REST API

Best for: any language, serverless environments, custom integrations, and all management operations regardless of language. The SDK is a thin wrapper around this API.

Base URL: `https://api.adaline.ai/v2`

Authentication: `Authorization: Bearer ADALINE_API_KEY`

### Adaline Proxy (zero-code)

Best for: quick start with zero instrumentation code. Change your LLM client's base URL to `gateway.adaline.ai` — Adaline intercepts the request, forwards it to the provider, and automatically creates a trace and span. No SDK required.

Use this when you want observability immediately without modifying application code.

## Recommended Integration Order

Work through these steps to get full value from Adaline:

1. **adaline-logs** — instrument your application to send traces and spans. This gives you immediate observability: latency, cost, errors, and prompt inputs/outputs visible in the dashboard.

2. **adaline-deployments** — move prompt text out of your code and into Adaline. Fetch the active deployed prompt at runtime using `GET /deployments` on the v2 API base URL. This decouples prompt changes from application code releases.

3. **adaline-datasets** — build datasets of representative inputs (and optionally expected outputs) for your use cases. These become the inputs to evaluations.

4. **adaline-evaluators** — define how to score prompt outputs: exact match, regex, JSON schema, or LLM-as-judge with a custom rubric.

5. **adaline-evaluations** — run a prompt version against a dataset using your evaluators. Use this as a quality gate before promoting a prompt to production.

6. **adaline-providers** — discover which LLM providers and models are configured in your Adaline workspace. Use this to avoid hardcoding provider IDs or model names.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ADALINE_API_KEY` | Required | Bearer token for all API calls |
| `ADALINE_PROJECT_ID` | Recommended | Project to associate logs with |
| `ADALINE_PROMPT_ID` | Conditional | Required when fetching a deployed prompt |
| `ADALINE_DEPLOYMENT_ENVIRONMENT_ID` | Conditional | Required when fetching environment-specific deployments (dev/staging/prod) |

## Runtime Detection Guide

Determine the right approach for your environment:

- TypeScript/JavaScript project: use the TypeScript SDK for logging, deployment fetching, and typed namespace clients; use raw REST only when the SDK surface is not convenient
- Python project: use the async Python SDK for logging, deployment fetching, and typed namespace clients; use raw REST only when needed
- Other language (Go, Ruby, Java, etc.): use the REST API for all operations
- Quick prototype or zero-code start: use the Adaline Proxy — change your LLM client's base URL to `gateway.adaline.ai`
- Serverless functions (Lambda, Cloud Functions): use the REST API directly; call `flush()` or await the POST before the function returns to avoid losing buffered spans

## Authentication

Every REST request requires a Bearer token in the Authorization header:

```
Authorization: Bearer ADALINE_API_KEY
```

All request and response bodies are JSON. Timestamps in the public API are Unix milliseconds unless an endpoint explicitly says otherwise.

## Error Handling

Retry strategy for REST API calls:

- Retry on: `5xx` server errors
- Do not retry on: `4xx` client errors — these indicate a problem with the request or credentials
- Exponential backoff: wait 1s before first retry, 2s before second, 4s before third, cap at 10s
- Maximum retries: 3

Common errors:

| Status | Meaning | Action |
|--------|---------|--------|
| 401 | Invalid or missing API key | Check `ADALINE_API_KEY` value |
| 403 | Key does not have access to this resource | Verify project membership and key permissions |
| 404 | Resource not found | Check IDs (projectId, promptId, datasetId, etc.) |
| 429 | Rate limited | Retry with exponential backoff |
| 400 | Validation error | Check request body against the skill's API reference |
| 500/502/503 | Server error | Retry with exponential backoff |

## References

See references/api-context.md for the current v2 API endpoints grouped by resource with the skill that covers each.
See references/typescript-sdk-context.md for the TypeScript SDK overview and key methods.
See references/python-sdk-context.md for the Python SDK overview with async support.