Agent frameworks / Claude Agent SDK

Connect an agent built on the Claude Agent SDK to AIX through the MCP server, in TypeScript or Python, with the tool permissions and the rules the model needs.

The Claude Agent SDK runs the same agent loop as Claude Code, and MCP is its native way to add tools. Register AIX as an HTTP server, allow its tools, and the agent can submit_intent after any turn that states or changes what the shopper wants to buy and report_handoff before the shopper is sent to a store. The key stays in your server's environment.

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: userMessage,
  options: {
    systemPrompt: AIX_RULES, // see below
    mcpServers: {
      aix: {
        type: "http",
        url: "https://aix.brambles.ai/api/aix/mcp",
        headers: { Authorization: `Bearer ${process.env.AIX_PUBLISHER_KEY}` },
      },
    },
    allowedTools: ["mcp__aix__submit_intent", "mcp__aix__report_handoff"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Python

import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query


async def main(user_message: str) -> None:
    options = ClaudeAgentOptions(
        system_prompt=AIX_RULES,  # see below
        mcp_servers={
            "aix": {
                "type": "http",
                "url": "https://aix.brambles.ai/api/aix/mcp",
                "headers": {"Authorization": f"Bearer {os.environ['AIX_PUBLISHER_KEY']}"},
            }
        },
        allowed_tools=["mcp__aix__submit_intent", "mcp__aix__report_handoff"],
    )
    async for message in query(prompt=user_message, options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main("..."))

MCP tools are named mcp__<server>__<tool>, so mcp__aix__* allows every tool the key exposes: for a publisher key submit_intent, report_handoff, delete_session and get_activity. Listing the two the shopper flow needs keeps the agent from calling the rest. The submit_intent tool takes one argument, intent, with the same body as POST /intents (its turn input is reserved for Brambles-managed publishers; the model must send exactly one of the two). The same server block works in a project's .mcp.json with "${AIX_PUBLISHER_KEY}" in the header.

Prefer allowedTools over permissionMode: "bypassPermissions": it grants exactly the AIX tools and nothing more.

The rules the model needs

Put this in the system prompt (systemPrompt / system_prompt):

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.

Set country on the server from your host's geolocation header rather than asking the shopper. Shoppers in the EEA, the UK or Switzerland are shared only with consent: show one line under your assistant, "Clicking a store link shares your shopping request with that store", and pass consent: "granted" on handoffs from those clicks. Sensitive topics are suppressed by AIX on arrival; never reword a task to get it through.

Receiving side

A store's agent uses the same server block with AIX_RECEIVER_KEY; the tools then list deliveries (subscribe_intents), read one receipt (get_intent_context), acknowledge it (acknowledge_delivery) and redeem a handoff id from a landing or a checkout (redeem_handoff; with a sandbox key it returns a free test delivery for any well-formed id). Verification and acknowledgment belong on your server, not in the model's hands; see Receiving agents.

Test it

1. Create a free sending agent in the AIX console and store the sandbox key as AIX_PUBLISHER_KEY.
2. Run one conversation that names a product and ends with a store link. The init system message lists aix as connected; the intent answers accepted; the handoff answers test_delivered with a receiver_preview.
3. GET /activity with the same key, or the AIX console, shows the test. Create the production key there and set it in production.