> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiagentshouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common problems and issues you may encounter when using the AI Agents House SDK.

This guide provides solutions to common issues that can arise when implementing and using the AI Agents House SDK.

## Initial Setup Issues

<AccordionGroup>
  <Accordion title="`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:**

    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`.

    ```javascript theme={null}
    // Correct
    import dotenv from 'dotenv';
    dotenv.config();
    import { AgentMonitor } from '@agent-governance/node';
    const monitor = new AgentMonitor({ apiKey: process.env.AGENT_GOVERNANCE_API_KEY, ... });
    ```

    3. **Typo Check:** Verify there are no typos in the variable name (`AGENT_GOVERNANCE_API_KEY`) or the `apiKey` property in the constructor.
  </Accordion>

  <Accordion title="`Failed to register agent: HTTP 401 Unauthorized`">
    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 AI Agents House account.
  </Accordion>

  <Accordion title="`Invalid configuration: endpoint: Invalid endpoint URL format`">
    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`.
  </Accordion>
</AccordionGroup>

## Event Tracking Issues

<AccordionGroup>
  <Accordion title="Events are not appearing on the dashboard">
    You are tracking events in your code, but nothing shows up in the AI Agents House 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 AI Agents House 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}
    ```
  </Accordion>

  <Accordion title="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.

    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.
  </Accordion>
</AccordionGroup>

## Compliance Engine Issues

<AccordionGroup>
  <Accordion title="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:**

    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`.
  </Accordion>

  <Accordion title="Getting too many false positive violations">
    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)`.
  </Accordion>
</AccordionGroup>

## Integration Wrapper Issues (Anthropic/OpenAI)

<AccordionGroup>
  <Accordion title="Wrapped client throws an error or doesn't work">
    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 AI Agents House 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.
  </Accordion>

  <Accordion title="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:**

    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).
  </Accordion>
</AccordionGroup>

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.