Structuring AI Response for Better API Alignment

Ever tried to make AI-generated responses fit into a strict JSON format or an API contract and found it frustrating? You’re not alone. In this article, we’ll keep it simple and show you practical ways to align flexible AI outputs with structured API requirements. By the end, you’ll have a solid example and some tips to make this integration process much easier.

The Challenge

AI responses, especially those generated by large language models (LLMs), are often unstructured or semi-structured. While they are excellent at processing complex tasks and generating natural language, their outputs don’t always align neatly with the structured formats required by APIs. This discrepancy can lead to issues such as:

• Parsing complexity: Converting free-form text into a structured format can be error-prone.
• Inconsistency: Variability in AI-generated responses can disrupt API workflows.
• Performance overhead: Additional processing to align AI responses with APIs can impact latency.

Practical Example: AI Agent for Flight Booking

1. Clarify Missing Details: The AI should ask the user for additional information, such as the departure location and travel dates. Example exchange:

• User: "Find me a flight to London."
• AI: "From which city are you departing, and what are your travel dates?"

1. Generate a Structured Payload: Once the user provides the necessary details (e.g., “From New York on February 1st, returning February 28th”), the AI should create a payload that aligns with the flight booking API’s schema. The payload might look like this:

   {
     "from": "New York",
     "to": "London",
     "dateOut": "01/02/2025",
     "dateBack": "28/02/2025"
   }

Options for Structuring AI Responses

Prompt Engineering

Provide detailed instructions in the system message, explicitly outlining the desired JSON structure for the response. Include examples of the required format.

{
  "from": "<CityName if provided>",
  "to": "<CityName if provided>",
  "dateOut": "<Date in Format DD/MM/YY if provided>",
  "dateBack": "<Date in Format DD/MM/YY if provided>"
}

If some data is missing, return:

{
  "enhanceRequest": "<Add here request for missing data>"
}

JSON Schema Response Format

Utilize OpenAI’s JSON Schema response format to define a schema that the model follows, ensuring responses are in the desired JSON format.

Implementation Example:

const desiredSchema = {
  name: 'flight_search',
  strict: false,
  schema: {
    description: 'Search for flights with departure and return dates.',
    parameters: {
      type: 'object',
      properties: {
        from: { type: 'string', description: 'The departure city name.' },
        to: { type: 'string', description: 'The destination city name.' },
        dateOut: { type: 'string', format: 'date', description: 'The outbound flight date' },
        dateBack: { type: 'string', format: 'date', description: 'The return flight date' }
      },
      required: ['from', 'to', 'dateOut', 'dateBack']
    }
  }
};

const completion = await openai.beta.chat.completions.parse({
  response_format: {
    json_schema: desiredSchema,
    type: 'json_schema'
  },
  model: 'gpt-4o-2024-08-06',
  messages: [{ role: 'user', content: 'Find me a flight to London.' }]
});

Adding a System Message for Better Accuracy:

const completion = await openai.beta.chat.completions.parse({
  response_format: {
    json_schema: desiredSchema,
    type: 'json_schema'
  },
  model: 'gpt-4o-2024-08-06',
  messages: [
    {
      role: 'system',
      content: `You are an API assistant. Respond in JSON format. If some data is missing, return:
      {
        "enhanceRequest": "<Add here request for missing data>"
      }`
    },
    { role: 'user', content: 'Find me a flight to London.' }
  ]
});

Pros & Cons

Pros:

• Ensures strict adherence to the desired JSON structure.
• Reduces the need for extensive prompt engineering or post-processing.

Cons:

• May require initial setup to define appropriate schemas.
• Limited to models and platforms that support JSON mode.

Conclusion

Aligning AI responses with API requirements is crucial for building reliable and efficient integrations. By defining clear schemas, fine-tuning models, and implementing robust validation, developers can bridge the gap between unstructured AI outputs and structured API inputs. As AI continues to evolve, these strategies will be essential for creating systems that are both intelligent and practical.

About me site: https://danduh.me/
Follow me on

• Twitter
• Medium
• Dev.To
• LinkedIn
• YouTube
• GitHub

Feel free to ask a question.
Thanks a lot for reading!