Skip to content

Integration Guide

The most important thing to know first

The governance API is a non-blocking sidecar. If it is unavailable, your app must continue operating.

Your agent serves users. Governance observes your agent. These are two separate concerns. A downed governance API should never take down your product.

If you integrate the governance API as a required dependency — one that blocks your agent's response path — you have built a single point of failure into your product. Do not do this.

What happens if the API is down?

Nothing, if you integrate correctly.

The correct integration pattern is:

  1. Your agent generates a response
  2. You send the response to the governance API asynchronously or with a timeout
  3. You serve the agent response to your user regardless of what the governance API returns
  4. If the governance call fails, you log the miss locally and move on

The governance API records what your agent did. It does not control what your agent does.

Implementing failure-safe governance calls

Set a hard timeout

Never let a governance API call block your response path indefinitely. Set a timeout of 500ms–1000ms. If the API does not respond in time, log the miss and continue.

async function observeWithFallback(text: string, agentId: string, runId: string) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 1000); // 1s hard limit

  try {
    const response = await fetch('https://agentgovernance.dev/api/v1/observe/assess', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.GOVERNANCE_API_KEY}`,
      },
      body: JSON.stringify({ text, agentId, runId }),
      signal: controller.signal,
    });

    if (!response.ok) {
      console.warn(`[governance] observe failed: HTTP ${response.status}`);
      return null;
    }

    return await response.json();
  } catch (err: any) {
    if (err.name === 'AbortError') {
      console.warn('[governance] observe timed out — continuing without observation');
    } else {
      console.warn('[governance] observe error:', err.message);
    }
    return null; // fail open
  } finally {
    clearTimeout(timeout);
  }
}

import httpx
import logging

async def observe_with_fallback(text: str, agent_id: str, run_id: str):
    try:
        async with httpx.AsyncClient(timeout=1.0) as client:
            response = await client.post(
                'https://agentgovernance.dev/api/v1/observe/assess',
                headers={'Authorization': f'Bearer {os.environ["GOVERNANCE_API_KEY"]}'},
                json={'text': text, 'agentId': agent_id, 'runId': run_id},
            )
            response.raise_for_status()
            return response.json()
    except httpx.TimeoutException:
        logging.warning('[governance] observe timed out — continuing without observation')
        return None
    except Exception as e:
        logging.warning(f'[governance] observe error: {e}')
        return None  # fail open

Call governance after serving the response

In most architectures, you can fire the governance call after the response is already on its way to the user:

// Serve the agent response immediately
res.json({ answer: agentResponse });

// Observe in the background — does not block the response
observeWithFallback(agentResponse, agentId, runId).then((result) => {
  if (result) {
    console.log(`[governance] ${result.summary.patternsDetected} pattern(s) detected`);
  }
});

Log misses for later analysis

When a governance call fails, log enough information to reconstruct what was missed:

if (!result) {
  console.warn(JSON.stringify({
    event: 'governance_miss',
    agentId,
    runId,
    textLength: text.length,
    timestamp: new Date().toISOString(),
  }));
}

If you later need to reconcile your logs against governance data, the timestamp and agent context let you identify the gap.

Health check on startup

Before your app accepts traffic, verify that the governance API is reachable:

async function checkGovernanceHealth() {
  try {
    const res = await fetch('https://agentgovernance.dev/health', { signal: AbortSignal.timeout(3000) });
    if (res.ok) {
      console.log('[governance] API reachable');
    } else {
      console.warn('[governance] API returned non-200 — operating in degraded mode');
    }
  } catch {
    console.warn('[governance] API unreachable — operating without governance observation');
  }
}

Do not block startup on this check. Log the result and continue. Your app should operate in "degraded mode" (no governance observation) rather than refusing to start.

What "degraded mode" means

When the governance API is unavailable:

  • Your agent continues serving users normally
  • Pattern detection does not run on agent output
  • Gate events are not recorded
  • Behavioral observations are not stored

When the API comes back online:

  • New observations resume automatically
  • Past misses are not replayed (they are logged locally if you implement the miss logging above)
  • Gate state is preserved — your governance runs remain at whatever gate they were at

Rate limits

The governance API enforces daily rate limits per API key:

Tier Limit
Free (no key) 10 evaluations/day per IP
Registered key 100 evaluations/day
Team/Business Higher limits — contact support

If you hit a rate limit, the API returns HTTP 429 with a rateLimit object in the response body:

{
  "error": { "code": "RATE_LIMITED", "message": "Daily evaluation limit reached." },
  "rateLimit": { "limit": 100, "remaining": 0, "resetAt": "2026-03-12T00:00:00.000Z" }
}

resetAt is midnight UTC. Design your integration to handle 429 gracefully — treat it the same as a timeout (log and continue).

Before going to production:

  • Governance API calls have a hard timeout (≤1000ms recommended)
  • API failures return null and log a warning — they do not throw to the caller
  • Agent responses are served regardless of governance API status
  • Startup health check logs governance API reachability without blocking startup
  • Rate limit 429 responses are handled gracefully (log and continue)
  • GOVERNANCE_API_KEY is stored in environment secrets, never in source code
  • Governance calls run after the response is served where architecture permits

Common mistakes

Awaiting governance in the response path without a timeout If the API is slow, your users wait. Always set a timeout.

Throwing on governance failure A governance error should never propagate to your users. Catch it, log it, return null.

Storing your API key in source code Treat GOVERNANCE_API_KEY like a database password. Use environment secrets.

Assuming governance observation means the agent is safe Governance observes and flags — it does not prevent bad output from reaching users. Your application logic is still responsible for what gets served.

Next steps