Skip to main content
This guide provides solutions to common issues that can arise when implementing and using the Agent Governance SDK.

​
Initial Setup Issues

This is the most common error and means the apiKey passed to the AgentMonitor constructor was undefined or an empty string.Solution:
  1. Check Environment Variables: Ensure that AGENT_GOVERNANCE_API_KEY is correctly set in your environment (.env file, server configuration, etc.).
  2. Loading Order: Make sure you are loading your environment variables (e.g., with dotenv) before you initialize the AgentMonitor.
// Correct
import dotenv from 'dotenv';
dotenv.config();
import { AgentMonitor } from '@agent-governance/node';
const monitor = new AgentMonitor({ apiKey: process.env.AGENT_GOVERNANCE_API_KEY, ... });
  1. Typo Check: Verify there are no typos in the variable name (AGENT_GOVERNANCE_API_KEY) or the apiKey property in the constructor.
This error indicates that your API key is invalid or does not have the necessary permissions.Solution:
  1. Verify API Key: Double-check that the API key you are using is correct and has not been revoked.
  2. Check Organization ID: Ensure the organizationId you provided is correct and corresponds to the provided API key.
  3. Permissions: Confirm that the API key has permissions to register agents in your Agent Governance account.
The endpoint URL provided in the configuration is not a valid URL.Solution:
  1. Check URL Format: Ensure the URL starts with http:// or https:// and is a well-formed URL.
  2. Remove if Unnecessary: If you are not using a custom endpoint, you can remove the endpoint property from your configuration entirely, and it will default to https://api.aiagentshouse.com.

​
Event Tracking Issues

You are tracking events in your code, but nothing shows up in the Agent Governance dashboard.Solution:
  1. Check for shutdown() or flush(): The SDK batches events and sends them periodically. If your script finishes executing before a batch is sent, the events will be lost. Ensure you call await monitor.shutdown() at the end of your script or application lifecycle. For long-running services, this should be part of your graceful shutdown logic.
  2. Verify API Key and Org ID: Ensure you are using the correct credentials for the environment you are viewing on the dashboard.
  3. Check for Network Issues: Look at your application’s logs. Are there any errors related to network requests failing to reach the Agent Governance API endpoint? Firewalls or proxy issues can sometimes block outbound traffic.
  4. Enable Debug Logging: Temporarily set enableLogging: true and logLevel: 'debug' in your monitor configuration. This will print detailed logs from the SDK to your console, showing you when events are added to the batch and when flushes are attempted.
[AgentGovernance] [DEBUG] Event tracked {"agentId":"...","interactionType":"..."}
[AgentGovernance] [DEBUG] Events flushed successfully {"count":10}
Your application’s memory consumption increases over time when the SDK is enabled.Solution: This is almost always related to the event buffer growing without being flushed.
  1. Check Flush Configuration: A very large batchSize combined with a long flushInterval can cause many events to be held in memory. Consider lowering these values.
  2. Network Failures: If the SDK is consistently failing to send event batches to the API (due to network errors), it will re-queue the events and retry. This can cause the buffer to grow. Check your logs for repeated “Failed to flush events” errors.
  3. Graceful Shutdown: Ensure monitor.shutdown() is being called when your application exits. Otherwise, the final batch of events will remain in memory until the process is killed.

​
Compliance Engine Issues

You are sending messages that should trigger compliance rules (e.g., including an SSN), but no violations are being flagged.Solution:
  1. enableComplianceChecks: The most common reason is that enableComplianceChecks is either false or not set in the AgentMonitor configuration. It must be explicitly set to true.
  2. Event Type: The built-in compliance engine primarily runs on agent_response events. Ensure you are using monitor.trackAgentResponse() or an automated wrapper that calls it. Compliance checks do not run on user messages by default.
  3. Custom Rules: If you are using custom rules, ensure they have been added to the complianceEngine instance and that their isActive property is true.
The compliance engine is flagging content that is not actually a violation.Solution:
  1. Review Rule Logic: If it’s a built-in rule, please report the false positive to our support team with an example of the content that was incorrectly flagged.
  2. Refine Custom Rules: If it’s a custom rule, refine its logic. For example, if a regex is too broad, make it more specific. Use word boundaries (\b) to prevent matching substrings within larger words.
  3. Deactivate Problematic Rules: As a temporary measure, you can deactivate a specific rule that is causing issues using monitor.complianceEngine.setRuleActive('rule-id-here', false).

​
Integration Wrapper Issues (Anthropic/OpenAI)

After wrapping your LLM client, API calls start failing.Solution:
  1. SDK Version Compatibility: Ensure your LLM SDK version (e.g., openai or @anthropic-ai/sdk) is compatible with the version of the Agent Governance SDK you are using. Check our release notes for any known compatibility issues.
  2. Correct Wrapper: Make sure you are using the correct monitor and wrapper for your client (e.g., AnthropicAgentMonitor and wrapAnthropic for the Anthropic client).
  3. Agent Registration: You must await monitor.registerAgent(agentInfo) before you wrap the client and start making calls.
The wrapper is tracking text messages but not when the LLM decides to use a tool/function.Solution:
  1. Check LLM Response: The wrapper detects tool calls by inspecting the response from the LLM API. Log the raw response from the API to confirm that it includes the tool_use (for Anthropic) or function_call (for OpenAI) content block.
  2. Correct Method: Ensure you are using the correct method that supports tool calling (e.g., messages.create for Anthropic, chat.completions.create for OpenAI).
If you’re still facing issues, please enable debug logging and contact our support team at hello@aiagentshouse.com with the relevant logs and a description of the problem.
⌘I