> ## 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.
# OpenAI Integration
> Automatically monitor GPT API calls with seamless integration
The OpenAI integration provides automatic monitoring for GPT API calls with minimal code changes. Simply wrap your existing OpenAI client to start tracking all chat completions, token usage, costs, and compliance violations.
## Prerequisites
* `openai` package installed
* AI Agents House SDK installed
* Valid OpenAI and AI Agents House API keys
## Basic Setup
### Installation
If you haven't already, install both the OpenAI SDK and AI Agents House SDK:
```bash theme={null}
npm install openai @agent-governance/node
```
### Initialize the Monitor
Use the `OpenAIAgentMonitor` class for automatic GPT monitoring:
```javascript theme={null}
import { OpenAIAgentMonitor } from '@agent-governance/node';
import OpenAI from 'openai';
const monitor = new OpenAIAgentMonitor({
apiKey: 'your-governance-api-key',
organizationId: 'your-org-id',
environment: 'development',
enableComplianceChecks: true
});
```
### Register Your Agent
Register your GPT-powered agent with the monitoring system:
```javascript theme={null}
await monitor.registerAgent({
id: 'gpt-banking-assistant',
name: 'GPT Banking Assistant',
category: 'tool_calling',
specialty: 'customer_service',
version: '1.0.0',
llmProvider: 'openai',
model: 'gpt-4o',
description: 'GPT-4o powered customer service assistant',
complianceSettings: {
sr11_7_enabled: true,
fair_lending_monitoring: true,
bsa_aml_checks: true
}
});
```
### Wrap the OpenAI Client
Wrap your existing OpenAI client to enable automatic monitoring:
```javascript theme={null}
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY
});
// Wrap the client - all chat completion calls will now be monitored
const monitoredOpenAI = monitor.wrapOpenAI(openai, 'gpt-banking-assistant');
```
## Usage Examples
### Basic Chat Completion
Use the wrapped client exactly as you would the original openai client. All calls to `chat.completions.create` will be monitored automatically.
```javascript theme={null}
const response = await monitoredOpenAI.chat.completions.create({
model: 'gpt-4o-mini',
messages: [
{
role: 'system',
content: 'You are a helpful banking assistant.'
},
{
role: 'user',
content: 'Can you help me understand my account fees?'
}
],
max_tokens: 500
});
console.log(response.choices[0].message.content);
// Response: "I'd be happy to help explain your account fees..."
```
### With Function Calling
The integration automatically tracks when GPT decides to call functions (also known as tools).
```javascript theme={null}
const response = await monitoredOpenAI.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: 'What is my current checking account balance?'
}
],
tools: [
{
type: 'function',
function: {
name: 'get_account_balance',
description: 'Get the current balance for a specific account',
parameters: {
type: 'object',
properties: {
account_type: {
type: 'string',
description: 'Type of account (e.g., checking, savings)'
}
},
required: ['account_type']
}
}
}
],
tool_choice: 'auto'
});
// If GPT decides to call a function, it's automatically tracked.
// The 'tool_call' event is logged with the function name and arguments.
```
## Automatic Tracking Features
The OpenAI integration automatically captures:
* **Conversation Events**: User messages, agent responses, and function calls.
* **Performance Metrics**: API call latency, token usage (prompt and completion), and calculated costs.
* **Compliance Monitoring**: Real-time scanning of agent responses for PII, Fair Lending violations, and BSA/AML keywords.
## Cost Tracking
The integration automatically calculates costs based on OpenAI's pricing for various models.
* GPT-4o: $5 input / $15 output per 1M tokens
* GPT-4o Mini: $0.15 input / $0.60 output per 1M tokens
* GPT-4 Turbo: $10 input / $30 output per 1M tokens
* GPT-3.5 Turbo: $0.50 input / $1.50 output per 1M tokens
Costs are calculated based on the usage data returned by the API and are included in the tracked `agent_response` event.
## Best Practices
### Session Management
* For multi-turn conversations, configure a `sessionId` in the wrapper options to group all related API calls into a single session.
* Include a `userId` in the wrapper options to link interactions to specific customers for better analytics and audit trails.
### Function Integration
* Clearly define your function schemas with descriptive names and parameter descriptions to improve GPT's accuracy in calling them.
* Ensure your agent is registered with a `category` of `'tool_calling'` for proper analytics.
### Error Handling
* The wrapper preserves OpenAI's native error handling. All API errors are automatically tracked by the SDK and then re-thrown, so your existing `try/catch` blocks will work as expected.
## Troubleshooting
Ensure your `apiKey` and `organizationId` are correct. For scripts that exit quickly, you may need to call `await monitor.shutdown()` to ensure the final batch of events is sent.
Session context must be configured when you call `wrapOpenAI`. The OpenAI SDK does not have a built-in concept of a session, so you must provide it to the wrapper.
The SDK tracks function calls when the API response includes a `tool_calls` object. Verify that your prompt is successfully inducing the model to use your defined tools.
The wrapper identifies the user message by looking for the last message in the `messages` array with `role: 'user'`. Ensure your conversation history is structured correctly.
## Comparison with Manual Tracking
The OpenAI wrapper significantly simplifies the monitoring process.
```javascript theme={null}
// Wrap once, monitor everything
const monitoredOpenAI = monitor.wrapOpenAI(openai, 'agent-id', {sessionId: 'customer-session-123'});
const response = await monitoredOpenAI.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello' }]
});
// All tracking (user message, agent response, latency, cost) happens automatically.
```
```javascript theme={null}
// Manual tracking requires multiple explicit calls
const sessionId = 'customer-session-123';
monitor.trackUserMessage('agent-id', sessionId, 'Hello');
const startTime = Date.now();
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello' }]
});
const latency = Date.now() - startTime;
monitor.trackAgentResponse('agent-id', sessionId, response.choices[0].message.content, {
llmLatency: latency,
tokensUsed: response.usage,
// ... and you would need to calculate cost manually
});
```
## Next Steps
Learn about monitoring Claude models
Explore advanced event tracking capabilities for custom integrations.
Deep dive into real-time compliance monitoring.
Review advanced SDK configuration options.