Skip to main content

​
useAgentIntegrations

[!WARNING] Deprecation Notice: Agent Integrations will be phased out in future releases in favor of Model Context Protocol (MCP) servers utilizing useAgentMcpServers.
The useAgentIntegrations hook provides the core functionalities required for managing an AI agent’s connections to external services, such as Google Drive or Slack. This hook interfaces directly with the Frontend API (/agent/integrations), facilitating the retrieval of existing connections, the generation of secure OAuth consent URLs for new integrations, and the managed disconnection of existing services.

​
Parameters

​
agentName
string | null
The target agent’s identifier. Specifying this parameter ensures that all integration actions and data queries are scoped appropriately to a single agent’s context.

​
Hook Interface

​
integrations
AgentIntegration[]
An array containing all active and available integrations associated with the specified agent.
​
loading
boolean
Indicates whether the network request to retrieve the initial integrations list is currently in progress.
​
error
Error | null
Captures network failures or authorization errors encountered during data retrieval or mutation operations.
​
generateConsentURL
(integrationId: string) => Promise<ConsentURLResponse>
​
removeIntegration
(integrationId: string) => Promise<void>
​
refetch
() => Promise<void>

​
Data Structures

​
Usage Examples

​
Rendering Available Integrations

The integrations array can be utilized to construct an interface displaying connected services: 
import { useAgentIntegrations } from "@wacht/nextjs";

export function IntegrationsList({ agentName }: { agentName: string }) {
  const { integrations, loading, error } = useAgentIntegrations(agentName);

  if (loading) return <div>Loading integrations...</div>;
  if (error) return <div className="text-red-600">Failed to load integrations: {error.message}</div>;

  return (
    <ul className="space-y-3">
      {integrations.map((integration) => (
        <li key={integration.id} className="flex justify-between items-center border-b pb-2">
          <span className="font-medium">{integration.name}</span>
          {integration.is_active ? (
            <span className="text-sm font-semibold text-green-600">Connected</span>
          ) : (
            <span className="text-sm text-gray-400">Not configured</span>
          )}
        </li>
      ))}
    </ul>
  );
}

​
Establishing a New Connection

To initiate a new service connection, invoke generateConsentURL and redirect the user: 
import { useState } from "react";
import { useAgentIntegrations } from "@wacht/nextjs";

export function ConnectDrive({ agentName }: { agentName: string }) {
  const { generateConsentURL } = useAgentIntegrations(agentName);
  const [isRedirecting, setIsRedirecting] = useState(false);

  const handleConnection = async () => {
    setIsRedirecting(true);
    try {
      const { consent_url } = await generateConsentURL("google_drive");
      window.location.href = consent_url;
    } catch (err) {
      console.error("Initiation failed:", err);
      setIsRedirecting(false);
    }
  };

  return (
    <button 
      onClick={handleConnection} 
      disabled={isRedirecting}
      className="px-4 py-2 bg-blue-600 text-white rounded shadow-sm"
    >
      {isRedirecting ? "Connecting..." : "Connect Google Drive"}
    </button>
  );
}

​
Disconnecting a Service

To terminate an active integration, invoke the removeIntegration method: 
import { useAgentIntegrations } from "@wacht/nextjs";
import { useState } from "react";

export function DisconnectButton({ integrationId, agentName }: { integrationId: string; agentName: string }) {
  const { removeIntegration } = useAgentIntegrations(agentName);
  const [isRemoving, setIsRemoving] = useState(false);

  const handleDisconnect = async () => {
    setIsRemoving(true);
    try {
      await removeIntegration(integrationId);
    } finally {
      setIsRemoving(false);
    }
  };

  return (
    <button 
      onClick={handleDisconnect}
      disabled={isRemoving}
      className={`px-3 py-1 text-sm border rounded ${
        isRemoving ? "text-gray-400 border-gray-200" : "text-red-600 border-red-200 hover:bg-red-50"
      }`}
    >
      {isRemoving ? "Disconnecting..." : "Disconnect"}
    </button>
  );
}
  • useAgentContext - For interfacing directly with the agent through a chat interface.
  • useAgentSession - For resolving the active agent and initializing a real-time session.