adaline-integration

Adaline Integration Guide

What is Adaline

Adaline is the single platform to iterate, evaluate, deploy, and monitor 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
• Iterate — build and test prompts in the playground, version them, and collaborate with your team
• Evaluate — run prompts against datasets at scale using rule-based and LLM-as-judge evaluators to gate quality before shipping
• Deploy — ship prompt versions to environments (dev/staging/prod) and fetch them at runtime so your code always runs the latest approved prompt

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 a fluent API for creating traces and spans, handles buffering and flushing, and supports distributed tracing out of the box.

Install: npm install @adaline/client

Use for: logging (adaline-logs skill), fetching deployments (adaline-deployments skill). For management operations (creating prompts, datasets, evaluators) use the REST API directly.

Python SDK (adaline-client)

Best for: Python applications. Full feature parity with the TypeScript SDK. Supports both sync and async usage via asyncio.

Install: pip install adaline-client

Use for: logging (adaline-logs skill), fetching deployments (adaline-deployments skill). For management operations use the REST API directly.

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 /v2/deployments. This decouples prompt iteration from code deploys.

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 and deployment fetching; use the REST API for creating prompts, datasets, evaluators, and running evaluations
• Python project: use the Python SDK for logging and deployment fetching; use the REST API for management operations
• 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. All timestamps are ISO 8601 strings (e.g., "2024-01-15T10:00:00.000Z").

Error Handling

Retry strategy for REST API calls:

• Retry on: 429 Too Many Requests and 5xx server errors
• Do not retry on: 4xx client errors (except 429) — these indicate a problem with the request
• 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
422	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 all 39 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.