feat(firebaseai): code execution (#17661)

* init structure

* Add example

* make language enum and test for thought

* fix analyzers

* Address review comment

* fix analyzer

Author: cynthiajoan

packages/firebase_ai/firebase_ai/example/lib/pages/function_calling_page.dart

@@ -40,6 +40,7 @@ class Location {
 
 class _FunctionCallingPageState extends State<FunctionCallingPage> {
   late GenerativeModel _functionCallModel;
+  late GenerativeModel _codeExecutionModel;
   final List<MessageData> _messages = <MessageData>[];
   bool _loading = false;
   bool _enableThinking = false;
@@ -59,19 +60,33 @@ class _FunctionCallingPageState extends State<FunctionCallingPage> {
       var vertexAI = FirebaseAI.vertexAI(auth: FirebaseAuth.instance);
       _functionCallModel = vertexAI.generativeModel(
         model: 'gemini-2.5-flash',
+        generationConfig: generationConfig,
         tools: [
           Tool.functionDeclarations([fetchWeatherTool]),
         ],
+      );
+      _codeExecutionModel = vertexAI.generativeModel(
+        model: 'gemini-2.5-flash',
         generationConfig: generationConfig,
+        tools: [
+          Tool.codeExecution(),
+        ],
       );
     } else {
       var googleAI = FirebaseAI.googleAI(auth: FirebaseAuth.instance);
       _functionCallModel = googleAI.generativeModel(
         model: 'gemini-2.5-flash',
+        generationConfig: generationConfig,
         tools: [
           Tool.functionDeclarations([fetchWeatherTool]),
         ],
+      );
+      _codeExecutionModel = googleAI.generativeModel(
+        model: 'gemini-2.5-flash',
         generationConfig: generationConfig,
+        tools: [
+          Tool.codeExecution(),
+        ],
       );
     }
   }
@@ -169,6 +184,17 @@ class _FunctionCallingPageState extends State<FunctionCallingPage> {
                       child: const Text('Test Function Calling'),
                     ),
                   ),
+                  const SizedBox(width: 8),
+                  Expanded(
+                    child: ElevatedButton(
+                      onPressed: !_loading
+                          ? () async {
+                              await _testCodeExecution();
+                            }
+                          : null,
+                      child: const Text('Test Code Execution'),
+                    ),
+                  ),
                 ],
               ),
             ),
@@ -243,6 +269,67 @@ class _FunctionCallingPageState extends State<FunctionCallingPage> {
     }
   }
 
+  Future<void> _testCodeExecution() async {
+    setState(() {
+      _loading = true;
+    });
+    try {
+      final codeExecutionChat = _codeExecutionModel.startChat();
+      const prompt = 'What is the sum of the first 50 prime numbers? '
+          'Generate and run code for the calculation, and make sure you get all 50.';
+
+      _messages.add(MessageData(text: prompt, fromUser: true));
+
+      final response =
+          await codeExecutionChat.sendMessage(Content.text(prompt));
+
+      final thought = response.thoughtSummary;
+      if (thought != null) {
+        _messages
+            .add(MessageData(text: thought, fromUser: false, isThought: true));
+      }
+
+      final buffer = StringBuffer();
+      for (final part in response.candidates.first.content.parts) {
+        if (part is ExecutableCodePart) {
+          buffer.writeln('Executable Code:');
+          buffer.writeln('Language: ${part.language}');
+          buffer.writeln('Code:');
+          buffer.writeln(part.code);
+        } else if (part is CodeExecutionResultPart) {
+          buffer.writeln('Code Execution Result:');
+          buffer.writeln('Outcome: ${part.outcome}');
+          buffer.writeln('Output:');
+          buffer.writeln(part.output);
+        } else if (part is TextPart) {
+          buffer.writeln(part.text);
+        }
+      }
+
+      if (buffer.isNotEmpty) {
+        _messages.add(
+          MessageData(
+            text: buffer.toString(),
+            fromUser: false,
+          ),
+        );
+      }
+
+      setState(() {
+        _loading = false;
+      });
+    } catch (e) {
+      _showError(e.toString());
+      setState(() {
+        _loading = false;
+      });
+    } finally {
+      setState(() {
+        _loading = false;
+      });
+    }
+  }
+
   void _showError(String message) {
     showDialog<void>(
       context: context,

packages/firebase_ai/firebase_ai/lib/firebase_ai.dart

@@ -44,6 +44,8 @@ export 'src/content.dart'
         FunctionResponse,
         Part,
         TextPart,
+        ExecutableCodePart,
+        CodeExecutionResultPart,
         UnknownPart;
 export 'src/error.dart'
     show
@@ -104,4 +106,6 @@ export 'src/tool.dart'
         FunctionCallingMode,
         FunctionDeclaration,
         Tool,
-        ToolConfig;
+        ToolConfig,
+        GoogleSearch,
+        CodeExecution;

packages/firebase_ai/firebase_ai/lib/src/api.dart

@@ -211,7 +211,6 @@ final class UsageMetadata {
 
 /// Response candidate generated from a [GenerativeModel].
 final class Candidate {
-  // TODO: token count?
   // ignore: public_member_api_docs
   Candidate(this.content, this.safetyRatings, this.citationMetadata,
       this.finishReason, this.finishMessage,
@@ -1173,15 +1172,15 @@ final class VertexSerialization implements SerializationStrategy {
         _parsePromptFeedback(promptFeedback),
       _ => null,
     };
-    final usageMedata = switch (jsonObject) {
+    final usageMetadata = switch (jsonObject) {
       {'usageMetadata': final usageMetadata?} =>
         parseUsageMetadata(usageMetadata),
       {'totalTokens': final int totalTokens} =>
         UsageMetadata._(totalTokenCount: totalTokens),
       _ => null,
     };
     return GenerateContentResponse(candidates, promptFeedback,
-        usageMetadata: usageMedata);
+        usageMetadata: usageMetadata);
   }
 
   /// Parse the json to [CountTokensResponse]
@@ -1523,3 +1522,64 @@ SearchEntryPoint _parseSearchEntryPoint(Object? jsonObject) {
     renderedContent: renderedContent,
   );
 }
+
+/// Supported programming languages for the generated code.
+enum CodeLanguage {
+  /// Unspecified status. This value should not be used.
+  unspecified('LANGUAGE_UNSPECIFIED'),
+
+  /// Python language.
+  python('PYTHON');
+
+  const CodeLanguage(this._jsonString);
+
+  final String _jsonString;
+
+  /// Convert to json format.
+  String toJson() => _jsonString;
+
+  /// Parse the json string to [CodeLanguage].
+  static CodeLanguage parseValue(String jsonObject) {
+    return switch (jsonObject) {
+      'LANGUAGE_UNSPECIFIED' => CodeLanguage.unspecified,
+      'PYTHON' => CodeLanguage.python,
+      _ => CodeLanguage
+          .unspecified, // If backend has new change, return unspecified.
+    };
+  }
+}
+
+/// Represents the result of the code execution.
+enum Outcome {
+  /// Unspecified status. This value should not be used.
+  unspecified('OUTCOME_UNSPECIFIED'),
+
+  /// Code execution completed successfully.
+  ok('OUTCOME_OK'),
+
+  /// Code execution finished but with a failure. `stderr` should contain the
+  /// reason.
+  failed('OUTCOME_FAILED'),
+
+  /// Code execution ran for too long, and was cancelled. There may or may not
+  /// be a partial output present.
+  deadlineExceeded('OUTCOME_DEADLINE_EXCEEDED');
+
+  const Outcome(this._jsonString);
+
+  final String _jsonString;
+
+  /// Convert to json format.
+  String toJson() => _jsonString;
+
+  /// Parse the json string to [Outcome].
+  static Outcome parseValue(String jsonObject) {
+    return switch (jsonObject) {
+      'OUTCOME_UNSPECIFIED' => Outcome.unspecified,
+      'OUTCOME_OK' => Outcome.ok,
+      'OUTCOME_FAILED' => Outcome.failed,
+      'OUTCOME_DEADLINE_EXCEEDED' => Outcome.deadlineExceeded,
+      _ => throw FormatException('Unhandled Outcome format', jsonObject),
+    };
+  }
+}

packages/firebase_ai/firebase_ai/lib/src/content.dart

@@ -16,6 +16,7 @@ import 'dart:convert';
 import 'dart:developer';
 import 'dart:typed_data';
 
+import 'api.dart';
 import 'error.dart';
 
 /// The base structured datatype containing multi-part content of a message.
@@ -114,6 +115,32 @@ Part parsePart(Object? jsonObject) {
       throw unhandledFormat('functionCall', functionCall);
     }
   }
+  if (jsonObject.containsKey('executableCode')) {
+    final executableCode = jsonObject['executableCode'];
+    if (executableCode is Map &&
+        executableCode.containsKey('language') &&
+        executableCode.containsKey('code')) {
+      return ExecutableCodePart(
+        language: CodeLanguage.parseValue(executableCode['language'] as String),
+        code: executableCode['code'] as String,
+      );
+    } else {
+      throw unhandledFormat('executableCode', executableCode);
+    }
+  }
+  if (jsonObject.containsKey('codeExecutionResult')) {
+    final codeExecutionResult = jsonObject['codeExecutionResult'];
+    if (codeExecutionResult is Map &&
+        codeExecutionResult.containsKey('outcome') &&
+        codeExecutionResult.containsKey('output')) {
+      return CodeExecutionResultPart(
+        outcome: Outcome.parseValue(codeExecutionResult['outcome'] as String),
+        output: codeExecutionResult['output'] as String,
+      );
+    } else {
+      throw unhandledFormat('codeExecutionResult', codeExecutionResult);
+    }
+  }
   return switch (jsonObject) {
     {'text': final String text} => TextPart._(text,
         isThought: isThought, thoughtSignature: thoughtSignature),
@@ -353,3 +380,51 @@ final class FileData extends Part {
         'file_data': {'file_uri': fileUri, 'mime_type': mimeType}
       };
 }
+
+/// A `Part` that represents the code that is executed by the model.
+final class ExecutableCodePart extends Part {
+  // ignore: public_member_api_docs
+  ExecutableCodePart({
+    required this.language,
+    required this.code,
+    bool? isThought,
+  }) : super(
+          isThought: isThought,
+          thoughtSignature: null,
+        );
+
+  /// The programming language of the code.
+  final CodeLanguage language;
+
+  /// The source code to be executed.
+  final String code;
+
+  @override
+  Object toJson() => {
+        'executableCode': {'language': language.toJson(), 'code': code}
+      };
+}
+
+/// A `Part` that represents the code execution result from the model.
+final class CodeExecutionResultPart extends Part {
+  // ignore: public_member_api_docs
+  CodeExecutionResultPart({
+    required this.outcome,
+    required this.output,
+    bool? isThought,
+  }) : super(
+          isThought: isThought,
+          thoughtSignature: null,
+        );
+
+  /// The result of the execution.
+  final Outcome outcome;
+
+  /// The stdout from the code execution, or an error message if it failed.
+  final String output;
+
+  @override
+  Object toJson() => {
+        'codeExecutionResult': {'outcome': outcome.toJson(), 'output': output}
+      };
+}

packages/firebase_ai/firebase_ai/lib/src/tool.dart

@@ -21,12 +21,12 @@ import 'schema.dart';
 /// knowledge and scope of the model.
 final class Tool {
   // ignore: public_member_api_docs
-  Tool._(this._functionDeclarations, this._googleSearch);
+  Tool._(this._functionDeclarations, this._googleSearch, this._codeExecution);
 
   /// Returns a [Tool] instance with list of [FunctionDeclaration].
   static Tool functionDeclarations(
       List<FunctionDeclaration> functionDeclarations) {
-    return Tool._(functionDeclarations, null);
+    return Tool._(functionDeclarations, null, null);
   }
 
   /// Creates a tool that allows the model to use Grounding with Google Search.
@@ -47,7 +47,13 @@ final class Tool {
   ///
   /// Returns a `Tool` configured for Google Search.
   static Tool googleSearch({GoogleSearch googleSearch = const GoogleSearch()}) {
-    return Tool._(null, googleSearch);
+    return Tool._(null, googleSearch, null);
+  }
+
+  /// Returns a [Tool] instance that enables the model to use Code Execution.
+  static Tool codeExecution(
+      {CodeExecution codeExecution = const CodeExecution()}) {
+    return Tool._(null, null, codeExecution);
   }
 
   /// A list of `FunctionDeclarations` available to the model that can be used
@@ -65,13 +71,18 @@ final class Tool {
   /// responses.
   final GoogleSearch? _googleSearch;
 
+  /// A tool that allows the model to use Code Execution.
+  final CodeExecution? _codeExecution;
+
   /// Convert to json object.
   Map<String, Object> toJson() => {
         if (_functionDeclarations case final _functionDeclarations?)
           'functionDeclarations':
               _functionDeclarations.map((f) => f.toJson()).toList(),
         if (_googleSearch case final _googleSearch?)
-          'googleSearch': _googleSearch.toJson()
+          'googleSearch': _googleSearch.toJson(),
+        if (_codeExecution case final _codeExecution?)
+          'codeExecution': _codeExecution.toJson()
       };
 }
 
@@ -93,6 +104,15 @@ final class GoogleSearch {
   Map<String, Object> toJson() => {};
 }
 
+/// A tool that allows the model to use Code Execution.
+final class CodeExecution {
+  // ignore: public_member_api_docs
+  const CodeExecution();
+
+  /// Convert to json object.
+  Map<String, Object> toJson() => {};
+}
+
 /// Structured representation of a function declaration as defined by the
 /// [OpenAPI 3.03 specification](https://spec.openapis.org/oas/v3.0.3).
 ///