Skip to content

SDK_INTEGRATION.md

Latest commit

 

History

History
416 lines (308 loc) · 9.74 KB

SDK_INTEGRATION.md

File metadata and controls

416 lines (308 loc) · 9.74 KB

SDK & API Integration Guide

How to integrate AAIP into existing AI platforms, frameworks, and SDKs.

For transport bindings (gRPC, WebSocket, MCP), see BINDINGS.md.

Overview

Most AI agent frameworks use standard HTTP clients. Adding AAIP typically involves:

  1. Configuring global/default headers
  2. Wrapping the HTTP client with middleware

Integration Matrix

Platform/SDK Method Where Visible
LangChain Request wrapper config Server logs
AutoGPT HTTP client config Server logs
Semantic Kernel HttpClient middleware Server logs
CrewAI Agent config Server logs
Playwright Browser context headers Network tab, server logs
Selenium Proxy or extension Server logs
OpenAI SDK httpx client config Server logs
Anthropic SDK httpx client config Server logs

Framework Integrations

LangChain

from langchain_community.utilities import RequestsWrapper

# v2 format with agent ID and capabilities
headers = {
    "AI-Agent": "OpenAI/GPT-5.2 (LangChain; 0.2.0) [aid=langchain-001]",
    "AI-Agent-Capabilities": "cap:browse;tools:web_search"
}
requests_wrapper = RequestsWrapper(headers=headers)

# Use in a chain
from langchain_community.tools import RequestsGetTool
tool = RequestsGetTool(requests_wrapper=requests_wrapper)

For WebResearchRetriever:

from langchain.retrievers.web_research import WebResearchRetriever

# The retriever uses requests internally
# Patch or configure the underlying session
import requests
original_get = requests.get

def patched_get(*args, **kwargs):
    kwargs.setdefault('headers', {})
    kwargs['headers']['AI-Agent'] = 'OpenAI/GPT-5.2 (LangChain; 0.1.50)'
    return original_get(*args, **kwargs)

requests.get = patched_get

AutoGPT

Configure headers in your AutoGPT settings:

# In autogpt startup or config
CUSTOM_HEADERS = {
    "AI-Agent": "OpenAI/GPT-5.2 (AutoGPT; 0.5.0) [aid=autogpt-001]",
    "AI-Agent-Capabilities": "cap:execute;tools:web_search,code_exec"
}

Global patch:

import aiohttp

AI_AGENT = "OpenAI/GPT-5.2 (AutoGPT; 0.5.0) [aid=autogpt-001]"

original_init = aiohttp.ClientSession.__init__

def patched_init(self, *args, **kwargs):
    headers = kwargs.get('headers', {})
    headers['AI-Agent'] = AI_AGENT
    kwargs['headers'] = headers
    original_init(self, *args, **kwargs)

aiohttp.ClientSession.__init__ = patched_init

Microsoft Semantic Kernel

Use delegating handlers to add headers to all requests:

// Create a custom delegating handler
public class AIAgentHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        request.Headers.Add("AI-Agent", 
            "Azure/openai-GPT-5.2 (SemanticKernel; 1.0) {tools:bing_search}");
        return await base.SendAsync(request, cancellationToken);
    }
}

// Register with HttpClient
var handler = new AIAgentHandler 
{ 
    InnerHandler = new HttpClientHandler() 
};
var httpClient = new HttpClient(handler);

// Use with Semantic Kernel
var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(
        "deployment", 
        "endpoint", 
        "key",
        httpClient: httpClient)
    .Build();

CrewAI

CrewAI agents can be configured with custom HTTP settings:

from crewai import Agent, Task, Crew
import os

# Set via environment or config
os.environ['AI_AGENT_HEADER'] = 'OpenAI/GPT-5.2 (CrewAI; 0.1.0) {tools:web_search}'

# Or patch the underlying httpx/requests client
import httpx

class AIAgentClient(httpx.Client):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.headers['AI-Agent'] = 'OpenAI/GPT-5.2 (CrewAI; 0.1.0)'

# Use throughout CrewAI

Browser Automation

Playwright (JavaScript)

const { chromium } = require('playwright');

const browser = await chromium.launch();
const context = await browser.newContext({
  extraHTTPHeaders: {
    'AI-Agent': 'Anthropic/claude-4.5 (WebCrawler; 1.0) [Playwright/1.40] {tools:web_search}'
  }
});

const page = await context.newPage();
await page.goto('https://example.com');

Playwright (Python)

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context(
        extra_http_headers={
            'AI-Agent': 'OpenAI/GPT-5.2 (Crawler; 2.0) [Playwright]'
        }
    )
    page = context.new_page()
    page.goto('https://example.com')

Selenium

Selenium doesn't natively support custom HTTP headers. Options:

Option 1: Browser Extension

// Create an extension that injects headers
// manifest.json
{
  "name": "AI-Agent Header",
  "version": "1.0",
  "manifest_version": 3,
  "permissions": ["webRequest", "webRequestBlocking"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    details.requestHeaders.push({
      name: "AI-Agent",
      value: "OpenAI/GPT-5.2 (Selenium; 4.10) [Chrome]"
    });
    return { requestHeaders: details.requestHeaders };
  },
  { urls: ["<all_urls>"] },
  ["blocking", "requestHeaders"]
);

Option 2: Proxy (mitmproxy)

# mitmproxy script to inject header
def request(flow):
    flow.request.headers["AI-Agent"] = "OpenAI/GPT-5.2 (Selenium; 4.10)"

Puppeteer

const puppeteer = require('puppeteer');

const browser = await puppeteer.launch();
const page = await browser.newPage();

await page.setExtraHTTPHeaders({
  'AI-Agent': 'OpenAI/GPT-5.2 (Scraper; 1.0) [Puppeteer/22]'
});

await page.goto('https://example.com');

API SDKs

OpenAI Python SDK

The OpenAI SDK doesn't directly expose custom header support for API calls, but you can use httpx:

import httpx
from openai import OpenAI

# Create custom httpx client
http_client = httpx.Client(
    headers={"AI-Agent": "OpenAI/GPT-5.2 (MyApp; 1.0)"}
)

# Pass to OpenAI client
client = OpenAI(http_client=http_client)

For external browsing requests (not API calls):

# If your agent makes web requests separately from OpenAI calls
import requests

session = requests.Session()
session.headers['AI-Agent'] = 'OpenAI/GPT-5.2 (WebAgent; 1.0) {tools:web_search}'

# Use for all web browsing
response = session.get('https://example.com')

Anthropic Python SDK

Similar approach with httpx:

import httpx
from anthropic import Anthropic

http_client = httpx.Client(
    headers={"AI-Agent": "Anthropic/claude-4.5-opus (MyApp; 2.0)"}
)

client = Anthropic(http_client=http_client)

Google Generative AI

import google.generativeai as genai
import httpx

# For web requests made by your agent
class AIAgentTransport(httpx.HTTPTransport):
    def handle_request(self, request):
        request.headers['AI-Agent'] = 'Google/gemini-3-pro-preview (MyApp; 1.0)'
        return super().handle_request(request)

Enterprise Patterns

Global Header Injection (Python)

For organizations wanting all outbound requests to include the header:

# Inject at application startup
import requests
import httpx
import aiohttp

AI_AGENT_STRING = "YourCompany/internal-model (EnterpriseAgent; 3.0) {tools:internal}"

# Patch requests
_original_request = requests.Session.request
def _patched_request(self, method, url, **kwargs):
    kwargs.setdefault('headers', {})
    kwargs['headers'].setdefault('AI-Agent', AI_AGENT_STRING)
    return _original_request(self, method, url, **kwargs)
requests.Session.request = _patched_request

# Patch httpx (sync)
_original_httpx_request = httpx.Client.request
def _patched_httpx_request(self, method, url, **kwargs):
    kwargs.setdefault('headers', {})
    kwargs['headers'].setdefault('AI-Agent', AI_AGENT_STRING)
    return _original_httpx_request(self, method, url, **kwargs)
httpx.Client.request = _patched_httpx_request

Proxy Injection

Use a corporate proxy to inject headers for all AI traffic:

# mitmproxy addon
from mitmproxy import http

AI_AGENT = "YourCompany/model (Gateway; 1.0)"

class AddAIAgent:
    def request(self, flow: http.HTTPFlow):
        flow.request.headers["AI-Agent"] = AI_AGENT

addons = [AddAIAgent()]

Environment Variable Pattern

import os

# Standard environment variable for AI-Agent
AI_AGENT = os.environ.get('AI_AGENT_HEADER', 
    f"{os.environ.get('AI_VENDOR', 'Unknown')}/{os.environ.get('AI_MODEL', 'unknown')} "
    f"({os.environ.get('APP_NAME', 'App')}; {os.environ.get('APP_VERSION', 'unknown')})"
)

Visibility and Verification

Where to See the Header

Context How to Verify
Server logs Check request headers in your web server logs
Network tab Browser DevTools → Network → Headers
Proxy tools mitmproxy, Charles, Fiddler
httpbin Send request to https://httpbin.org/headers

Test Your Implementation

# Quick test with httpbin
curl -H "AI-Agent: OpenAI/GPT-5.2 (Test; 1.0)" https://httpbin.org/headers

# Response will show your header:
# {
#   "headers": {
#     "Ai-Agent": "OpenAI/GPT-5.2 (Test; 1.0)",
#     ...
#   }
# }

Limitations & Notes

SDK/Platform Limitation
Selenium Requires extension or proxy for header injection
Some cloud functions May strip custom headers; verify with your provider
API-only SDKs Header visible only server-side, not in browser network tab
Rate-limited APIs Adding headers won't bypass rate limits

Contributing

If you've integrated AAIP into another framework, please submit a PR with your integration guide!