OpenAI Agents SDK

import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def run(user_message: str, session_id: str) -> str:
    async with MCPServerStreamableHttp(
        name="aix",
        params={
            "url": "https://aix.brambles.ai/api/aix/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['AIX_PUBLISHER_KEY']}"},
            "timeout": 10,
        },
        cache_tools_list=True,
    ) as server:
        agent = Agent(
            name="Shopping assistant",
            instructions=AIX_RULES,  # see below
            mcp_servers=[server],
        )
        result = await Runner.run(agent, user_message)
        return result.final_output

import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";

const aix = new MCPServerStreamableHttp({
  name: "aix",
  url: "https://aix.brambles.ai/api/aix/mcp",
  requestInit: { headers: { Authorization: `Bearer ${process.env.AIX_PUBLISHER_KEY}` } },
});

await aix.connect();
try {
  const agent = new Agent({ name: "Shopping assistant", instructions: AIX_RULES, mcpServers: [aix] });
  const result = await run(agent, userMessage);
  console.log(result.finalOutput);
} finally {
  await aix.close();
}

import { Agent, hostedMcpTool } from "@openai/agents";

const agent = new Agent({
  name: "Shopping assistant",
  instructions: AIX_RULES,
  tools: [
    hostedMcpTool({
      serverLabel: "aix",
      serverUrl: "https://aix.brambles.ai/api/aix/mcp",
      authorization: process.env.AIX_PUBLISHER_KEY,
      requireApproval: "never",
    }),
  ],
});

{
  "model": "gpt-5.5",
  "tools": [
    {
      "type": "mcp",
      "server_label": "aix",
      "server_url": "https://aix.brambles.ai/api/aix/mcp",
      "headers": { "Authorization": "Bearer <AIX_PUBLISHER_KEY>" },
      "require_approval": "never"
    }
  ],
  "input": "..."
}

import os
from typing import Literal, NotRequired, TypedDict

import httpx
from agents import Agent, function_tool

AIX = "https://aix.brambles.ai/api/aix"


class Budget(TypedDict):
    currency: str
    max_cents: int


class Fact(TypedDict):
    attribute: Literal["brand", "width", "size", "department", "use_case", "feature", "merchant", "deal"]
    value: str
    strength: Literal["required", "preferred", "excluded"]


class Task(TypedDict):
    category: str
    summary: str
    budget: NotRequired[Budget]
    facts: list[Fact]


class Intent(TypedDict):
    session_id: str
    country: str
    task: Task


async def _aix(path: str, body: dict) -> dict:
    key = os.environ.get("AIX_PUBLISHER_KEY")
    if not key:
        return {"status": "skipped", "reason": "no_key"}
    try:
        async with httpx.AsyncClient(timeout=3) as client:
            r = await client.post(f"{AIX}/{path}", json=body, headers={"Authorization": f"Bearer {key}"})
            return r.json() if r.is_success else {"status": "skipped", "reason": f"http_{r.status_code}"}
    except httpx.HTTPError:
        return {"status": "skipped", "reason": "timeout"}  # never block the shopper


@function_tool
async def submit_intent(intent: Intent) -> dict:
    """Report the shopper's current shopping task to AIX. Call after any turn that states or changes
    what they want to buy, with intent: session_id, country and the task. Shopping requirements only,
    never personal data."""
    return await _aix("intents", dict(intent))


@function_tool
async def report_handoff(session_id: str, destination_url: str, consent: str | None = None) -> dict:
    """Report that the shopper is being sent to a store or product page (the store's own URL).
    Use the returned landing_url as that page's URL, inside your affiliate link if you use one."""
    body: dict = {"session_id": session_id, "destination_url": destination_url}
    if consent:
        body["consent"] = consent
    return await _aix("handoffs", body)


agent = Agent(name="Shopping assistant", instructions=AIX_RULES, tools=[submit_intent, report_handoff])

You can send shopping intent to the Agentic Intent Exchange (AIX).
- After any user turn that states or changes what they want to buy, call submit_intent with one
  argument, intent: an object holding the conversation's session_id, the shopper's two-letter
  country, and the task: a category, a one-line summary, the budget when they gave one, and facts
  with attribute, value and strength (required, preferred or excluded). Send only shopping
  requirements: never names, emails, phone numbers, addresses, account or order numbers, or the
  conversation itself.
- Before you give the user a link to a store or product page, call report_handoff with the same
  session_id and the store's page URL, then use the returned landing_url as that page's URL (inside
  your own affiliate or ad link, if you use one).
- If either tool fails or is slow, carry on without it. Never ask the user for a key.