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:

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.

1. 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.

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

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

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

1. 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

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:

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.