Guides
Troubleshooting
Solutions to common problems and issues you may encounter when using the Agent Governance SDK.
This guide provides solutions to common issues that can arise when implementing and using the Agent Governance SDK.
If you’re still facing issues, please enable debug logging and contact our support team at
Initial Setup Issues
`ValidationError: apiKey is required`
`ValidationError: apiKey is required`
This is the most common error and means the
apiKey passed to the AgentMonitor constructor was undefined or an empty string.Solution:- Check Environment Variables: Ensure that
AGENT_GOVERNANCE_API_KEYis correctly set in your environment (.envfile, server configuration, etc.). - Loading Order: Make sure you are loading your environment variables (e.g., with
dotenv) before you initialize theAgentMonitor.
- Typo Check: Verify there are no typos in the variable name (
AGENT_GOVERNANCE_API_KEY) or theapiKeyproperty in the constructor.
`Failed to register agent: HTTP 401 Unauthorized`
`Failed to register agent: HTTP 401 Unauthorized`
`Invalid configuration: endpoint: Invalid endpoint URL format`
`Invalid configuration: endpoint: Invalid endpoint URL format`
The
endpoint URL provided in the configuration is not a valid URL.Solution:- Check URL Format: Ensure the URL starts with
http://orhttps://and is a well-formed URL. - Remove if Unnecessary: If you are not using a custom endpoint, you can remove the
endpointproperty from your configuration entirely, and it will default tohttps://api.aiagentshouse.com.
Event Tracking Issues
Events are not appearing on the dashboard
Events are not appearing on the dashboard
You are tracking events in your code, but nothing shows up in the Agent Governance dashboard.Solution:
- Check for
shutdown()orflush(): 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 callawait monitor.shutdown()at the end of your script or application lifecycle. For long-running services, this should be part of your graceful shutdown logic. - Verify API Key and Org ID: Ensure you are using the correct credentials for the environment you are viewing on the dashboard.
- 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.
- Enable Debug Logging: Temporarily set
enableLogging: trueandlogLevel: '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.
High memory usage in my application
High memory usage in my application
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.
- Check Flush Configuration: A very large
batchSizecombined with a longflushIntervalcan cause many events to be held in memory. Consider lowering these values. - 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.
- 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
Compliance violations are not being detected
Compliance violations are not being detected
You are sending messages that should trigger compliance rules (e.g., including an SSN), but no violations are being flagged.Solution:
enableComplianceChecks: The most common reason is thatenableComplianceChecksis eitherfalseor not set in theAgentMonitorconfiguration. It must be explicitly set totrue.- Event Type: The built-in compliance engine primarily runs on
agent_responseevents. Ensure you are usingmonitor.trackAgentResponse()or an automated wrapper that calls it. Compliance checks do not run on user messages by default. - Custom Rules: If you are using custom rules, ensure they have been added to the
complianceEngineinstance and that theirisActiveproperty istrue.
Getting too many false positive violations
Getting too many false positive violations
The compliance engine is flagging content that is not actually a violation.Solution:
- 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.
- 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. - 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)
Wrapped client throws an error or doesn't work
Wrapped client throws an error or doesn't work
After wrapping your LLM client, API calls start failing.Solution:
- SDK Version Compatibility: Ensure your LLM SDK version (e.g.,
openaior@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. - Correct Wrapper: Make sure you are using the correct monitor and wrapper for your client (e.g.,
AnthropicAgentMonitorandwrapAnthropicfor the Anthropic client). - Agent Registration: You must
await monitor.registerAgent(agentInfo)before you wrap the client and start making calls.
Tool calls or function calls are not being tracked
Tool calls or function calls are not being tracked
The wrapper is tracking text messages but not when the LLM decides to use a tool/function.Solution:
- 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) orfunction_call(for OpenAI) content block. - Correct Method: Ensure you are using the correct method that supports tool calling (e.g.,
messages.createfor Anthropic,chat.completions.createfor OpenAI).
hello@aiagentshouse.com with the relevant logs and a description of the problem.