Building a reliable AI feature that works well in production is not so easy; it's a completely different skill.
For this part 2, we're going to focus on three critical skills every AI Engineer needs, i.e
- Mastering Structured AI Outputs
- Real-Time Streaming
- Building a Robust Error Handling System
By the end, we will know how to build AI features that are cleaner, more predictable, and much more enterprise-ready.
What You'll Learn in This Part:
- Why free-text AI responses are dangerous to production Flutter Apps
- How to force structured, typed responses using Gemini
- How to implement streaming for better user experience in Flutter
- How to handle AI failures gracefully in Flutter
Structured Output
Let's start with Structured Output.
When you ask an AI model a question, by default, it returns free text (plain text), which is flexible but dangerous and hard to work with in real applications.
Structured Output allows the model to return clean, predictable data, usually in JSON format, just like when we are integrating an endpoint.
Here is an example of how to do this properly with Gemini in Flutter.
Future<ArticleBlueprint> generateStructuredBlueprint(
String topicPrompt, {
void Function(int attempt, Duration delay, Exception error)? onRetry,
}) async {
return RetryHelper.retryWithBackoff<ArticleBlueprint>(
onRetry: onRetry,
maxAttempts: 3,
action: () async {
GoogleAIClient? client;
try {
// 1. Initialize client using googleai_dart
client = GoogleAIClient(
config: GoogleAIConfig(
authProvider: ApiKeyProvider(apiKey),
),
);
// 2. Build Structured JSON prompt enforcing strict schema
final systemPrompt = '''
You are a technical content architect. Generate a structured JSON blueprint for a technical article or feature guide.
STRICT JSON SCHEMA REQUIREMENT:
Return ONLY a valid JSON object with the following fields:
- "title": String (compelling article title)
- "overview": String (concise 2-3 sentence overview)
- "difficulty": String ("Beginner", "Intermediate", or "Advanced")
- "estimatedReadingMinutes": Integer
- "tags": Array of Strings
- "keyConcepts": Array of Strings (up to 4 bullet points)
- "implementationSteps": Array of Strings (step-by-step implementation guide)
- "codeSnippet": String (short code example)
Topic to generate blueprint for:
"$topicPrompt"
''';
// 3. Make API request using client.models.generateContent
final response = await client.models.generateContent(
model: modelName,
request: GenerateContentRequest(
contents: [
Content(
parts: [TextPart(systemPrompt)],
role: 'user',
),
],
),
);
// 4. Extract generated text payload
final candidate = response.candidates?.firstOrNull;
if (candidate?.finishReason == FinishReason.safety ||
candidate?.finishReason?.name.toLowerCase() == 'safety') {
throw const SafetyRefusalAIException(
'The requested topic was flagged by Gemini safety filters.',
);
}
final parts = candidate?.content?.parts ?? [];
final rawText = parts
.whereType<TextPart>()
.map((p) => p.text)
.join('\n');
if (rawText.isEmpty) {
throw const SchemaParsingAIException(
'Received empty output from Gemini model.',
rawOutput: '',
);
}
// 5. Clean markdown code blocks & parse JSON
final cleanJsonText = _cleanMarkdownJson(rawText);
final jsonMap = jsonDecode(cleanJsonText) as Map<String, dynamic>;
// 6. Deserialize into strongly-typed Dart model
return ArticleBlueprint.fromJson(jsonMap, rawText);
} catch (e) {
throw _translateException(e);
} finally {
client?.close();
}
},
);
}This alone will make the AI feature more reliable.
Streaming Responses
Next up is Real-Time Streaming
Nobody likes staring at a loading spinner while waiting for a long AI response. With streaming, we can let the text appear gradually, just like a typewriter, which feels much more natural and responsive.
Let's implement streaming with Gemini in Flutter
/// Token Streaming (`streamGenerateContent`).
///
/// Yields incremental text tokens as they arrive from Gemini in real-time.
Stream<String> streamTextContent(String prompt) async* {
GoogleAIClient? client;
try {
client = GoogleAIClient(
config: GoogleAIConfig(
authProvider: ApiKeyProvider(apiKey),
),
);
final stream = client.models.streamGenerateContent(
model: modelName,
request: GenerateContentRequest(
contents: [
Content(
parts: [TextPart(prompt)],
role: 'user',
),
],
),
);
await for (final response in stream) {
final candidate = response.candidates?.firstOrNull;
final parts = candidate?.content?.parts ?? [];
final token = parts
.whereType<TextPart>()
.map((p) => p.text)
.join();
if (token.isNotEmpty) {
yield token;
}
}
} catch (e) {
throw _translateException(e);
} finally {
client?.close();
}
}As simple as that…
Error Handling & Resilience
This is the part most devs skip, and it's one of the reasons many AI features break in production.
AI calls can fail for many reasons:
- Network issues
- Rate limits
- Invalid responses
- Timeouts
- Model refusing the request
Let's create a simulation of a proper error handling system that includes:
- Clear error types
- Retry logic
- Meaningful feedback to the user
- Fallback behaviour
/// DEMO HELPER: Simulates intentional fault cases.
Future<ArticleBlueprint> simulateFault(String faultType) async {
await Future.delayed(const Duration(milliseconds: 600));
switch (faultType) {
case '429_rate_limit':
throw const RateLimitAIException(
'HTTP 429: Too Many Requests. Gemini rate limit reached.',
retryAfter: Duration(seconds: 5),
);
case 'network_timeout':
throw const NetworkAIException(
'SocketException: Connection timed out while reaching api.generativeai.google',
);
case 'schema_invalid':
throw const SchemaParsingAIException(
'FormatException: Missing mandatory "title" key in JSON payload.',
rawOutput: '{"overview": "Broken JSON example without title"}',
);
case 'safety_refusal':
throw const SafetyRefusalAIException(
'Prompt blocked by Gemini Safety Classifier Policy.',
);
default:
throw const UnknownAIException('Simulated unknown exception.');
}
}Now we can combine everything we've learned into a more complete example.
Source code on GitHub
https://github.com/techwithsam/ai_engineer_for_flutter_devs/blob/video-2
Recap & Key Takeaways
Today we covered:
- Always prefer Structured Output when you need predictable data
- Use streaming to improve perceived performance
- Treat error handling as a priority and first-class citizen
These three practices will immediately raise the quality of any AI feature you build in Flutter.
If you haven't already, download the free AI Engineering Starter Pack — I've updated it with the code and patterns from this article.
Here: techwithsam.dev/ai-starter-kit-2
Just enter your email, and it will be sent to you instantly.
If you found this valuable, please hit the like clap, follow, and turn on notifications so you don't miss the rest of this series.
In the next release, we'll go into AI Agents and Workflows
Drop a comment and tell me: What's one AI feature you want to build in your Flutter app?
Thank you for following. I'll see you in the next one.
Take care!
