Quick Start

Connect your first AI agent to Gradaris in under 10 minutes. Choose your path: Python SDK for engineers, webhook connector for no-code platforms, or manual registration for ungoverned agents.

Before you begin

You will need a Gradaris account and an API key. Both are available on the free tier — no credit card required.

1

Create your account

Visit gradaris.com and request early access. You will receive your credentials by email within one business day.

2

Retrieve your API key

Navigate to Settings → API Keys in your Gradaris dashboard. Copy your key — it will not be shown again.

3

Choose your integration path

Use the SDK for Python-based agents, the webhook connector for no-code platforms, or manual registration for agents that cannot be instrumented.

Path A — Python SDK

The Gradaris SDK wraps any Python-based AI agent with zero latency impact. Telemetry is sent asynchronously in a background thread.

Installation

bash
pip install gradaris-sdk

Basic instrumentation

python
import gradaris
from gradaris import Agent, RunConfig

# Initialize once at startup
gradaris.init(api_key="grd_your_api_key_here")

# Register your agent
agent = Agent(
    name="loan-eligibility-v2",
    description="Evaluates personal loan applications",
    risk_tier="high",         # "high" | "limited" | "minimal"
    eu_ai_act_category="annex-iii",  # EU AI Act classification
)

# Wrap your agent run — telemetry is captured automatically
with agent.run(RunConfig(session_id="session-abc")) as run:
    result = your_existing_agent_function(inputs)
    run.record_output(result)

The SDK captures input/output hashes, token counts, latency, and error signals automatically. No additional instrumentation is required for a baseline GGS assessment.

Async usage (recommended for production)

python
import asyncio
import gradaris

gradaris.init(api_key="grd_your_api_key_here")

async def run_agent(inputs):
    async with agent.arun() as run:
        result = await your_async_agent(inputs)
        await run.arecord_output(result)
    return result

Path B — Webhook Connector

If your agent runs on Make, Zapier, Power Automate, n8n, or any platform that can send an HTTP POST, use the webhook connector.

Endpoint

http
POST https://api.gradaris.com/v1/ingest
Content-Type: application/json
Authorization: Bearer grd_your_api_key_here

Payload schema

json
{
  "agent_id": "your-agent-identifier",
  "session_id": "unique-run-id",
  "input_hash": "sha256-of-input",      // optional but recommended
  "output_hash": "sha256-of-output",    // optional but recommended
  "latency_ms": 1240,
  "model": "gpt-4o",                    // model identifier
  "metadata": {}                       // any additional context
}

Never send raw PII or sensitive data in the payload. Send only SHA-256 hashes of inputs and outputs. This keeps Gradaris outside your data perimeter.

Path C — Manual Registration

For agents that cannot be instrumented — ChatGPT custom GPTs, Copilot agents, or third-party tools — use the manual registration form in the Gradaris dashboard.

Navigate to Agent Registry → Register Agent → Manual. Complete the plain-English questionnaire covering the agent's purpose, data sources, decision scope, and human oversight arrangements. Gradaris generates a governance baseline from your answers and assigns an initial GGS score.

Manual registration is the most important path for regulated industries. The agents most likely to trigger EU AI Act scrutiny are often the ones no one in IT knows about.

Viewing your first score

Once telemetry is flowing, your agent will appear in the Agent Registry within 60 seconds. Initial scoring typically completes within 5 minutes of the first run.

Each agent record shows:

  • Current GGS grade (A–F) with score breakdown by tier
  • EU AI Act article mapping with compliance indicators
  • Risk signal timeline — every detected anomaly, timestamped
  • Download links for PDF evidence packages
  • Cryptographic integrity hash for the current assessment

Downloading an evidence package

Navigate to your agent record and click Generate Report. Select the date range and applicable regulatory frameworks. The generated PDF is cryptographically signed and references the specific EU AI Act articles relevant to your agent's risk classification.

Next
Grading Framework →
Reference
Badges API →