Agentic Workflows

AI agents can perform powerful tasks within your e-commerce setup. Although there is no official Model Context Protocol (MCP) server available (yet), you can seamlessly integrate the Tweakwise App API into agentic workflows.

This document answers the question: How do I enable an AI agent to independently perform actions via the Tweakwise API?

Instead of figuring out the implementation for every call, you can use a two-step approach: you create a skill that uses a prompt to generate the required execution code one-time, and then execute that generated code directly in all subsequent runs.

Generating Custom Skills with LLMs

The tweakwise-add-redirect skill shown below is just one example. If you need your AI agent to interact with other Tweakwise endpoints (like fetching personalized recommendations or retrieving lister page configurations), you can simply ask your Large Language Model (LLM) to generate a similar skill definition for you.

Provide the LLM with the Tweakwise API documentation for the desired endpoint and use a prompt like:

"Act as a Tweakwise expert. Read the API documentation for the [Endpoint Name] endpoint and generate a skill definition similar to tweakwise-add-redirect that instructs an agent on how to build the correct API call, including necessary headers and payload requirements."

Implementation: Generate Once, Execute Often

To utilize this workflow, you first prompt the LLM to generate the code, and then you integrate that code into your agent's permanent toolset.

Step 1: The Generation Skill

Provide your LLM with the following system instruction to generate ready-to-run code for the Redirect_AddRedirect endpoint. Use this when you need the AI to write the integration script.

# Tweakwise Add Redirect
Generates ready-to-run code (Python, Node.js, cURL, etc.) to create a redirect using the Tweakwise App API (`Redirect_AddRedirect`).

**Requirements to gather**:
- Authentication: `instancekey` and `access_token`.
- `Type`: "Keyword" or "Attribute".
- `Url`: The destination redirect URL.
- `Terms`: A list of trigger terms (if `Type` is "Keyword").

**API Specification**:
- Method: `POST`
- URL: `https://app-api.tweakwise.com/redirect`
- Headers: `TWN-InstanceKey`, `TWN-Authentication`, `Content-Type: application/json`, `Accept: application/json`
- Allowed Body Parameters: `Type` (string), `Url` (string), `Terms` (array of strings), `CategoryId` (int), `AttributeId` (int), `UseConjugations` (boolean), `Exclusions` (string).

Step 2: Extract and Save the Code

When the agent uses the skill above, it will output a script. You save this script as an executable function in your environment.

Here is an example of the Node.js code the agent will generate based on the skill instructions:

// Generated executable function for subsequent runs
async function executeTweakwiseRedirect(termsArray, targetUrl) {
    const instanceKey = process.env.TWN_INSTANCE_KEY;
    const accessToken = process.env.TWN_ACCESS_TOKEN;
    
    // Check https://docs.tweakwise.com/mcp for specific endpoint documentation
    const response = await fetch(`https://app-api.tweakwise.com/redirect`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'TWN-InstanceKey': instanceKey,
            'TWN-Authentication': accessToken
        },
        body: JSON.stringify({
            Type: "Keyword",
            Url: targetUrl,
            Terms: termsArray
        })
    });

    if (!response.ok) {
        throw new Error(`Tweakwise API Error: ${response.statusText}`);
    }

    return await response.json();
}

Step 3: Subsequent Executions

Once the generated code is saved to your codebase, give your agent a simple JSON tool schema to call executeTweakwiseRedirect(termsArray, targetUrl). Your agent can now call this function natively in all future runs, skipping the generation step completely.

Important Considerations / Gotchas

• Custom Authentication Headers: You must include BOTH TWN-InstanceKey and TWN-Authentication in the headers. Do not use the standard Bearer token format, as the API will reject it.
• Enum Strictness: The Type property is an enum and usually takes "Keyword" or "Attribute".
• Validation and Human-in-the-Loop: Never let an agent blindly execute state-changing actions without a validation step. Build a mechanism where you must first approve the AI's proposed redirects.

Frequently Asked Questions (FAQ)

1. How do I handle authentication when using the App API?
Store your TWN-InstanceKey and TWN-Authentication (access token) securely in your server's environment variables. Pass them strictly as custom headers as shown in the generated code, never as a Bearer token.

2. Can I use endpoints if there is no formal MCP support yet?
Yes. The current REST API endpoints are fully usable via standard HTTP requests. MCP is just a standard protocol; as long as you use the generation skill to create the executable code, you can use any available endpoint.

3. My agent sometimes uses incorrect properties in the payload. How do I fix this?
If you modify the generation skill prompt, ensure it explicitly lists only the allowed parameters: Type, Url, Terms, CategoryId, AttributeId, UseConjugations, and Exclusions. This keeps the generated code strictly compliant with the Tweakwise API.